The Cloudlets API

Cloudlets are value-added applications that complement Akamai’s core delivery solutions to solve specific business challenges. Cloudlets bring a site’s business logic closer to the end user by placing it on the “edge” of the content delivery platform.

The Cloudlets v2 API allows you to create and view Cloudlet policies and policy versions. In addition, use this API to

  • activate a Cloudlet policy version on either the staging or production networks.

  • delete a Cloudlet policy.

  • view group-level information about a particular Cloudlet.

About This Document

This document includes the following sections:

  • Match Criteria provides information about constructing match rules for the various types of Cloudlets.

  • Debugging shows you how to deal with errors and warnings you may likely encounter.

  • Data provides information about the properties available with each endpoint.

  • JSON Schemas provides information about JSON schemas for this API.

  • Resources provides information about each operation available with this API.

Within this overview section, you can find the following information:

Cloudlets That Use This API

Use this API to set up the following Cloudlets:

  • Application Load Balancer (Beta): provides intelligent, scalable traffic management across physical, virtual, and cloud-hosted data centers without requiring the origin to send load feedback. This Cloudlet can automatically detect load conditions and route traffic to the optimal data source while maintaining custom routing policies and consistent visitor session behavior for your visitors.

  • API Prioritization: allows you to specify, for applications that call resources of various formats (like JSON or XML), which calls are given priority and are sent to the origin during high-demand situations. Based on information in the inbound request, you configure the rules that determine which calls are prioritized.

  • Audience Segmentation: provides hassle-free traffic segmentation and stickiness without degrading performance. This is often beneficial for A/B and multivariate testing.

  • Cloud Marketing (Beta): if you are MediaMath customer, allows you to add JavaScript tags to your site’s pages that can communicate with MediaMath without requiring a third-party call on every page.

  • Cloud Marketing Plus (Beta): if you are MediaMath customer, allows you to add JavaScript tags to your site’s pages that can communicate with MediaMath and its partners without requiring a third-party call on every page.

  • Edge Redirector: helps you more efficiently manage large numbers of redirects. By executing redirects at the Akamai Edge, you can reduce round trips to the origin and offload hits from your origin infrastructure.

  • Forward Rewrite: helps you create, based on in-bound request information, human-readable and search engine optimization-friendly (SEO-friendly) URLs for dynamically-generated pages.

  • Input Validation: helps protect your business by confirming that the values submitted into a web application are well-formed and comply with your custom policy. This Cloudlet also provides the ability to limit the number of valid form submissions and invalid attempts per user.

  • Phased Release: provides, at the edge, a mechanism to define a percentage of your visitors and direct them to a different origin while maintaining visitor stickiness.

  • Request Control: allows you to provide conditional access to your website or application by defining and managing whitelists and blacklists based on a number of match criteria, including the IP address and geography associated with incoming requests.

  • Visitor Prioritization: helps maintain business continuity for your dynamic application through the use of a waiting room page in high-demand situations.

IMPORTANT: This API does not support the Image Converter Cloudlet. Use the Property Manager API to enable the Image Converter behavior.

See Akamai’s Cloudlets page for additional information about the Cloudlets that are available today.

Getting Started

To get started with this API:

  • Contact your Akamai representative to enable the Cloudlets for your account.

  • Review the {OPEN} API Introduction section on available tools.

  • Review the {OPEN} API Provisioning section to create your OPEN API access credentials and authorizations, making sure you enable both read and write access for this API grant.

  • Get help from the {OPEN} developer community and provide feedback. You can also contact your Akamai representative for support. We want to hear from you!

NOTE: The maximum body size for Cloudlets POST requests is 5242880 bytes.

Concepts

Cloudlets Terminology

When working with Cloudlets, you need to be familiar with the following terms:

  • Policies: For each Cloudlet instance on your contract, there can be any number of policies. A single policy is associated with a single property configuration. Policies are versioned. Within a policy version you define the rules that determine when the Cloudlet executes. Each policy is assigned a unique ID (policyId).

  • Properties: A property configuration includes all the rules for how to process end-user requests for either a specific web asset or a set of assets. For more information about properties, see the Property Manager API.

  • Version: A specific revision of a given policy (policyId). Version numbers start at 1 and increment as new versions are created for a policy. You may want to create a new version of a policy to support a different business requirement, or to test new functionality. When you activate a Cloudlet, you are activating a specific version of a Cloudlet policy.

  • Groups: Within an account, there is a hierarchy of groups that control access to both properties and Cloudlets policies. If your Akamai username is not associated with the group (gid or groupId) being used with this API, then the request fails. In addition, you can only associate a Cloudlet policy with a property that is in a compatible group, which can either be the same group, or be an ancestor of the policy’s group.

  • Cloudlets Origins: A type of origin server that you can forward Cloudlets requests to. Cloudlets Origins are available for the following Cloudlets: Application Load Balancer, Audience Segmentation, Forward Rewrite, and Phased Release. The base rules for all Cloudlets Origins are set up in the Property Manager API. For Application Load Balancer, you use the Cloudlets Origin operations to set up and maintain load balancing configurations. For the other Cloudlets that support Cloudlets Origins, use the Property Association operations to view information about which Cloudlets Origins are associated with a particular Cloudlets policy version.

About Group IDs

When using this API, your level of access depends on the groups your Luna Control Center username is associated with. If your username is not associated with the group ID (gid or groupId) you selected, then the request fails.

To understand groups, you need to understand how accounts work at Akamai. Akamai customers access all their services using an account key. While administrators may have access to more than one account, in general they provision all their web assets under a single account. Customers typically set up groups that correspond to their firm’s own organizational hierarchy.

When using any of the GET operations available for this API, you may include the gid in the query parameter to associate the appropriate group with the request.

NOTE: You can change group-level information by changing role assignments in the User Admin API, or by either creating or deleting properties in the Property Manager API (PAPI).

Cloudlets API Workflow

The following is the basic workflow you need to follow when creating a new Cloudlet policy. For detailed information about the operations, see the Resources section. For information about the available properties, see the Data and Matches sections.

If you are using Cloudlets Origins or are setting up the Application Load Balancer Cloudlet, see Cloudlets API Workflow for Cloudlets Origins. Application Load Balancer always uses Cloudlets Origins.

  1. Run a GET request on the /cloudlets/api/v2/cloudlet-info endpoint to retrieve the ID (cloudletId) for the Cloudlet you are working with. You need the cloudletId when creating a new policy.

  2. Run a GET request on the /cloudlets/api/v2/group-info endpoint to retrieve information about which Cloudlets are associated with the groups you have edit privileges for. You will need the group IDs (groupId) returned when creating a Cloudlet policy.

  3. Using the /cloudlets/api/v2/policies endpoint, run a POST to create a Cloudlet policy using the cloudletId and groupId you retrieved from the previous steps. The policy created is version

  4. However, this new version does not have a description and does not include match rules (matchRules) attributes.

    NOTE: You have the option of using query parameters to clone an existing policy.

  5. Update version 1 of the new policy by running a PUT request on the /cloudlets/api/v2/policies/{policyId}/versions/{version} endpoint that includes a version description and match rules. The policyId is returned in the response when the Cloudlet policy is created.

  6. If you need to review the current property associations for the policy version before activating, run a GET request on the /cloudlets/api/v2/policies/{policyId}/properties endpoint.

    NOTE: This operation also returns information about any Cloudlets Origins configured on an associated property. If you are using a Cloudlet that supports Cloudlets Origins, you may want to verify that the information returned about these origins is accurate.

  7. Activate the policy by running a POST request to the /cloudlets/api/v2/policies/{policyId}/versions/{version}/activations endpoint.

  8. Using the Property Manager API (PAPI) set up the behavior for each Cloudlet you are configuring:

  9. Using PAPI, activate the property version that includes your Cloudlets behavior changes.

Cloudlets API Workflow for Cloudlets Origins

The following is the workflow you need to follow when creating a new Cloudlet policy that uses Cloudlets Origins. For detailed information about the operations, see the Resources section. For information about the available properties, see the Data and Matches sections.

  1. Using the Property Manager API (PAPI), set up the rules for any Cloudlets Origins that will support the Cloudlets policy.

  2. Run a GET request on the /cloudlets/api/v2/cloudlet-info endpoint to retrieve the ID (cloudletId) for the Cloudlet you are working with. You need the cloudletId when creating a new policy.

  3. Run a GET request on the /cloudlets/api/v2/group-info endpoint to retrieve information about which Cloudlets are associated with the groups you have edit privileges for. You will need the group IDs (groupId) returned when creating a Cloudlet policy.

  4. Using the /cloudlets/api/v2/policies endpoint, run a POST to create a Cloudlet policy using the cloudletId and groupId you retrieved from the previous steps. The policy created is version

  5. However, this new version does not have a description and does not include match rules (matchRules) attributes.

    NOTE: You have the option of using query parameters to clone an existing policy.

  6. Update version 1 of the new policy by running a PUT request on the /cloudlets/api/v2/policies/{policyId}/versions/{version} endpoint that includes a version description and match rules. The policyId is returned in the response when the Cloudlet policy is created.

  7. If you are setting up a load balancing configuration for Application Load Balancer complete the following tasks:

    1. Make a POST request to /cloudlets/api/v2/origins.

    2. Make a POST request to /cloudlets/api/v2/origins/{originId}/versions.

  8. If you need to review the current property associations for the policy version before activating, run a GET request on the /cloudlets/api/v2/policies/{policyId}/properties endpoint.

    NOTE: This operation also returns information about any Cloudlets Origins configured on an associated property.

  9. Using the Property Manager API (PAPI), set up the behavior for each Cloudlet you are configuring:

  10. Using PAPI, activate the property version that includes your Cloudlets behavior changes.

  11. If you are setting up a load balancing configuration for Application Load Balancer, make a POST request to /cloudlets/api/v2/origins/{originId}/activations to activate the load balancing version.

  12. Activate the policy by executing a POST request to the /cloudlets/api/v2/policies/{policyId}/versions/{version}/activations endpoint.

Interactions with Property Manager

Policy Activation

During policy activation you can associate a Cloudlets policy version with one or more properties that are within a compatible group.

You can do this by setting the additionalPropertyNames member in the activation request to the /cloudlets/api/v2/policies/{policyId}/versions/{version}/activations endpoint.

If you want to associate a property with a specific Cloudlets policy, use the Property Manager API to add the name of the Cloudlets policy to the Cloudlet behavior within the property.

Cloudlets Origins

A Cloudlets Origin is a type of origin server that you can forward Cloudlets requests to. You can use Cloudlets Origins with the following Cloudlets: Application Load Balancer, Audience Segmentation, Forward Rewrite, and Phased Release. The base rules for all Cloudlets Origins are set up in the Property Manager API. You do not need to activate the property version containing the Cloudlets Origins in order to use the Cloudlets Origins with the Cloudlets API. You only need to make the changes and issue a PUT request to save your changes.

Activation (Going Live)

The various activation operations allow you to activate a policy version on the selected network, or retrieve current or historical activation information for a Cloudlet policy.

To use the activation operations, you need to know the version of the policy you want to activate or view. The following are the activation statuses that are returned with the response:

  • inactive: The policy version has not been activated. No active property versions reference this policy.

  • active: The policy version is currently active (published) and its associated property version is also active.

  • deactivated: The policy version was previously activated but it has been superseded by a more recent activation of another policy version.

  • pending: The policy version is proceeding through the activation workflow.

  • failed: The policy version activation workflow has failed.

NOTE: If a failure occurs and you are not sure of the cause, be sure to include the statusDetail and the status code from the response in any tickets you file.

You can activate a policy version on a network if it is associated with a property and has a status of either inactive, failed, or deactivated. Policies with a pending status cannot be reactivated.

NOTE: Policies with no active versions do not contain activation information in the response body.

Activating Policy Versions

You can activate a policy version with a POST operation against the ../policies/nnn/activations endpoint, if you include the network and policyVersion attributes. In this case the policy is identified using the URI pathname.

If you include the network attribute in the request body, you can also activate a policy version by issuing a POST to the ../policies/nnn/versions/nnn/activations endpoint.

In addition, if the property version that references the Cloudlet policy is activated, an activation record is created.

NOTE: The property activation status is either active or inactive.

See the Resources section for examples of activation requests and responses.

Activation Times

The following are the average activation times for each Cloudlet:

Cloudlet Average Activation Time
Application Load Balancer 30 seconds to 1 minute
API Prioritization 30 seconds to 1 minute
Audience Segmentation 30 to 45 minutes
Cloud Marketing 30 seconds to 1 minute
Cloud Marketing Plus 30 seconds to 1 minute
Edge Redirector 30 to 45 minutes
Forward Rewrite 30 to 45 minutes
Input Validation 30 to 45 minutes
Phased Release 30 seconds to 1 minute
Request Control 30 seconds to 1 minute
Visitor Prioritization 30 seconds to 1 minute

NetStorage Activation Considerations

For NetStorage activations, Cloudlet policy activations either succeed or fail immediately. Once an activation is successful, the status changes to active, and the status of the previously active policy version changes to deactivated.

If an activation failure occurs, the status is still inactive, and the previously active policy version continues to be active. The response includes the reason for the failure.

Testing the Activated Policy

When activating a new policy, you should first deploy it to the staging network and then perform testing. Once testing is successfully completed, repeat the activation operations on the Production network to deploy your new policy.

Note that the associated property also has to be activated before you can begin testing. See the Activations section of the Property Manager API for more information.