Learn more:

• Cloudlets

• Akamai CLI for Visitor Prioritization

• Property Manager API

• PAPI Feature Catalog Reference

• Reporting API

Overview

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.

Cloudlets that use this API

Use this API to set up the following Cloudlets:

• Application Load Balancer: 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.

Get started

To get started with this API:

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

• Review Get Started for available tools.

• Review Authorize Your Client section to create your Akamai API access credentials and authorizations, making sure you enable both read and write access for this API grant.

• Get help from the Akamai 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 Akamai 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:

   • Application Load Balancer
   • API Prioritization
   • Audience Segmentation
   • Edge Redirector
   • Forward Rewrite
   • Input Validation
   • Request Control
   • Phased Release
   • Visitor Prioritization

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:

   • Application Load Balancer
   • Audience Segmentation
   • Forward Rewrite
   • Phased Release

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:

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.

Resources

The Cloudlets v2 API allows you to create and view Cloudlet policies and policy versions. Use this API to activate a Cloudlet policy version on either the staging or production network, delete a Cloudlet policy or a policy version, or view group-level information about a particular Cloudlet.

Operations listed under Load Balancing Configurations only apply to the Application Load Balancer Cloudlet. The /cloudlets/api/v2/conditional-origins?{policyId} endpoint that was previously used for Cloudlets Origins has been deprecated. The Property Associations operations return information about Cloudlets Origins.

API summary

List cloudlets

Returns name, code, and ID (cloudletId) information for all available Cloudlets. You need the cloudletId when creating a new Policy.

[
    {
        "serviceVersion": null,
        "apiVersion": "2.0",
        "location": "/cloudlets/api/v2/cloudlet-info/3",
        "cloudletId": 3,
        "cloudletCode": "FR",
        "cloudletName": "FORWARDREWRITE"
    },
    {
        "serviceVersion": null,
        "apiVersion": "2.0",
        "location": "/cloudlets/api/v2/cloudlet-info/0",
        "cloudletId": 0,
        "cloudletCode": "ER",
        "cloudletName": "EDGEREDIRECTOR"
    }
]

Get a cloudlet

Returns name, code, and ID information for a specific type of Cloudlet. You need the cloudletId when creating a new Policy.

{
    "serviceVersion": null,
    "apiVersion": "2.0",
    "location": "/cloudlets/api/v2/cloudlet-info/0",
    "cloudletId": 0,
    "cloudletCode": "ER",
    "cloudletName": "EDGEREDIRECTOR"
}

List groups

Returns information about the Cloudlet types associated with the groups you have edit privileges for.

[
    {
        "location": "/cloudlets/api/v2/group-info/1234",
        "serviceVersion": null,
        "apiVersion": "2.0",
        "groupId": 1234,
        "groupName": "Master Group Name",
        "parentId": 0,
        "capabilities": [
            {
                "cloudletId": 3,
                "cloudletCode": "FR",
                "capabilities": [
                    "View",
                    "Edit",
                    "Activate"
                ]
            },
            {
                "cloudletId": 0,
                "cloudletCode": "ER",
                "capabilities": [
                    "View",
                    "Edit",
                    "Activate",
                    "AdvancedEdit"
                ]
            }
            ],
        "properties": null
    },
    {
        "location": "/cloudlets/api/v2/group-info/5678",
        "serviceVersion": null,
        "apiVersion": "2.0",
        "groupId": 5678,
        "groupName": "Subgroup 1",
        "parentId": 1234,
        "capabilities": [
            {
                "cloudletId": 0,
                "cloudletCode": "ER",
                "capabilities": [
                    "View",
                    "Edit",
                    "Activate"
                ]
            }
            ],
        "properties": null
    }
]

Get a group

Returns information about the Cloudlet types associated with the selected group. For results to display, you must have edit privileges for one or more Cloudlet types within the group.

[
    {
        "location": "/cloudlets/api/v2/group-info/1234",
        "serviceVersion": null,
        "apiVersion": "2.0",
        "groupId": 1234,
        "groupName": "Master Group Name",
        "parentId": 0,
        "capabilities": [
            {
                "cloudletId": 3,
                "cloudletCode": "FR",
                "capabilities": [
                    "View",
                    "Edit",
                    "Activate"
                ]
            },
            {
                "cloudletId": 0,
                "cloudletCode": "ER",
                "capabilities": [
                    "View",
                    "Edit",
                    "Activate",
                    "AdvancedEdit"
                ]
            }
            ],
        "properties": null
    }
]

List policies

Returns information for all available policies.

[
    {
        "location": "/cloudlets/api/v2/policies/1001",
        "serviceVersion": null,
        "apiVersion": "2.0",
        "policyId": 1001,
        "cloudletId": 99,
        "cloudletCode": "CC",
        "groupId": 1234,
        "name": "CookieCutter",
        "description": "Custom cookie cutter",
        "propertyName": "www.example.org",
        "createdBy": "sjones",
        "createDate": 1400535431324,
        "lastModifiedBy": "sjones",
        "lastModifiedDate": 1441829042000,
        "activations": [
            {
                "serviceVersion": null,
                "apiVersion": "2.0",
                "network": "prod",
                "policyInfo": {
                    "policyId": 1001,
                    "name": "CookieCutter",
                    "version": 2,
                    "status": "INACTIVE",
                    "statusDetail": "waiting to complete tests in test environment",
                    "detailCode": 0,
                    "activatedBy": "jsmith",
                    "activationDate": 1441829042000
                },
                "propertyInfo": {
                    "name": "www.example.org",
                    "version": 2,
                    "groupId": 1234,
                    "status": "INACTIVE",
                    "activatedBy": "sjones",
                    "activationDate": 1441137842000
                }
            },
            {
                "serviceVersion": null,
                "apiVersion": "2.0",
                "network": "test",
                "policyInfo": {
                    "policyId": 1001,
                    "name": "CookieCutter",
                    "version": 22,
                    "status": "ACTIVE",
                    "statusDetail": "testing",
                    "detailCode": 0,
                    "activatedBy": "jsmith",
                    "activationDate": 1400535431000
                },
                "propertyInfo": {
                    "name": "www.example.org",
                    "version": 22,
                    "groupId": 1234,
                    "status": "ACTIVE",
                    "activatedBy": "jsmith",
                    "activationDate": 1441137842000
                }
            }
        ]
    }
]

Create a policy

Create a new Cloudlet policy. If a policy already exists with the same policy name, you receive a 409 (Conflict) status response that contains data for the existing policy. New policies are automatically assigned version number 1.

{
    "cloudletId": 99,
    "groupId": 1234,
    "name": "TestCreatePolicy1",
    "description": "Testing the creation of a policy"
}

{
    "location": "/cloudlets/api/v2/policies/1002",
    "serviceVersion": null,
    "apiVersion": "2.0",
    "policyId": 1002,
    "cloudletId": 99,
    "cloudletCode": "CC",
    "groupId": 1234,
    "name": "CreatePolicy1",
    "description": "Creating a policy",
    "deleted": false,
    "propertyName": null,
    "createdBy": "sjones",
    "createDate": 1428957069841,
    "lastModifiedBy": "jsmith",
    "lastModifiedDate": 1428957070000,
    "activations": []
}

Get a policy

Returns information about a specific Cloudlets policy.

{
    "location": "/cloudlets/api/v2/policies/1001",
    "serviceVersion": null,
    "apiVersion": "2.0",
    "policyId": 1001,
    "cloudletId": 99,
    "cloudletCode": "CC",
    "groupId": 1234,
    "name": "CookieCutter",
    "description": "Custom cookie cutter",
    "propertyName": "www.example.org",
    "createdBy": "jsmith",
    "createDate": 1428957070000,
    "lastModifiedBy": "sjones",
    "lastModifiedDate": 1441829042000,
    "activations": [
        {
            "serviceVersion": null,
            "apiVersion": "2.0",
            "network": "prod",
            "policyInfo": {
                "policyId": 1001,
                "name": "CookieCutter",
                "version": 2,
                "status": "INACTIVE",
                "statusDetail": "waiting to complete tests in test environment",
                "detailCode": 0,
                "activatedBy": "jsmith",
                "activationDate": 1433901173000
            },
            "propertyInfo": {
                "name": "www.example.org",
                "version": 2,
                "groupId": 1234,
                "status": "INACTIVE",
                "activatedBy": "sjones",
                "activationDate": 1441829042000
            }
        },
        {
            "serviceVersion": null,
            "apiVersion": "2.0",
            "network": "test",
            "policyInfo": {
                "policyId": 1001,
                "name": "CookieCutter",
                "version": 22,
                "status": "ACTIVE",
                "statusDetail": "testing",
                "detailCode": 0,
                "activatedBy": "jsmith",
                "activationDate": 1433901173000
            },
            "propertyInfo": {
                "name": "www.example.org",
                "version": 22,
                "groupId": 1234,
                "status": "ACTIVE",
                "activatedBy": "jsmith",
                "activationDate": 1441915442000
            }
        }
    ]
}

Update a policy

Update attributes of an existing policy.

When updating a policy, note the following:

• If you change the policy name, the new name must be unique.

• Changes to policy names are not allowed if the policy is currently associated with one or more properties.

• If a policy already exists with the same policy name, you receive a 409 (Conflict) status. The response contains data for the existing policy.

• If you are updating a previously deleted policy by setting its deleted attribute to false, the operation fails if there is a name conflict with another policy.

• The cloudletId and groupId are not required as they are for a POST request to this endpoint.

{
    "description": "Testing the update of a policy",
}

{
    "location": "/cloudlets/api/v2/policies/1002",
    "serviceVersion": null,
    "apiVersion": "2.0",
    "policyId": 1002,
    "cloudletId": 99,
    "cloudletCode": "CC",
    "groupId": 1234,
    "name": "CookieCutter",
    "description": "Testing the update of a policy",
    "deleted": false,
    "propertyName": null,
    "createdBy": "sjones",
    "createDate": 1428957070000,
    "lastModifiedBy": "jsmith",
    "lastModifiedDate": 1431549070000,
    "activations": []
}

Remove a policy

When you delete a policy, you can reuse the deleted policy’s name in another policy. Deleting a policy sets its deleted attribute to true, which hides the policy from normal GET requests and makes the policy name available for use on another policy. There are also the following considerations when you delete a policy:

• In Property Manager, if you try to reactivate an old property version that references the deleted policy, the operation fails.

• A policy cannot be deleted if it is currently included in the behavior set of some active property version.

NOTE: If the GET request specifies the includeDeleted parameter, the response includes deleted policies.

You can also undelete a policy by setting its deleted attribute to false with a PUT request against policies/{nnn}. However, if the policy name would conflict with the name of another policy that was created since the current policy was deleted, the operation fails. If the old name is no longer available, you can both undelete a policy and change its name in a single PUT request.

NOTE: A successful DELETE operation returns a status code of 204 (No Content).

List policy versions

Returns information about all versions of a policy.

[
    {
        "revisionId": 11868,
        "policyId": 1001,
        "version": 1,
        "description": "test",
        "createdBy": "jsmith",
        "createDate": 1427133615439,
        "lastModifiedBy": "sjones",
        "lastModifiedDate": 1427133651975,
        "activations": [],
        "matchRules": [],
        "rulesLocked": false
    },
    {
        "revisionId": 11870,
        "policyId": 1001,
        "version": 2,
        "description": "v2",
        "createdBy": "jsmith",
        "createDate": 1427133784903,
        "lastModifiedBy": "sjones",
        "lastModifiedDate": 1427133805767,
        "activations": [],
        "matchRules": [],
        "rulesLocked": false
    }
]

Create a new policy version

Create a new policy version, where the version number increments from the highest existing version. With this operation you can change any modifiable policy or version attributes.

The newly created policy version number is included in the response and is one number greater than the previously highest version. The default value for description is an empty string and there are no matchRules. However, if you use the cloneVersion query parameter with the POST request, then the default values for these attributes are taken from the latest version.

{
    "description": "Testing the cloning of a policy",
    "matchRuleFormat": "1.0",
    "matchRules": []
}

{
    "revisionId": 12345,
    "policyId": 1002,
    "version": 2,
    "description": "Cloning a policy",
    "createdBy": "sjones",
    "createDate": 1428957891084,
    "lastModifiedBy": "jsmith",
    "lastModifiedDate": 1428957891084,
    "activations": [],
    "matchRules": [],
    "rulesLocked": false
}

Get a policy version

Returns information about a specific Cloudlet policy version.

{
    "revisionId": 11870,
    "policyId": 1001,
    "version": 2,
    "description": "v2",
    "createdBy": "jsmith",
    "createDate": 1427133784903,
    "lastModifiedBy": "sjones",
    "lastModifiedDate": 1427133805767,
    "activations": [],
    "matchRules": [],
    "rulesLocked": false
}

Update a policy version

Update attributes of an existing policy version.

{ "description": "v1 for Q1 Sales" }

{
    "revisionId": 11870,
    "policyId": 1001,
    "version": 1,
    "description": "v1 for Q1 sales",
    "createdBy": "sjones",
    "createDate": 1427133784903,
    "lastModifiedBy": "sjones",
    "lastModifiedDate": 1427133805767,
    "activations": [],
    "matchRules": [],
    "rulesLocked": false
}

Remove a policy version

You have the option of removing policy versions, including those that are currently active on either the staging or production network. Once a policy version is deleted, you can still create a new policy version based on the deleted version.

Also, if you make changes to a deleted policy version, it is automatically undeleted and available for use.

When you remove a policy version, version numbers are not reallocated. For example, a policy has 15 versions, and you delete versions 14 and 15. The next version created would be 16, not 14.

A successful DELETE operation returns a status code of 204 (No Content).

Add a version rule

Add a new rule to an existing policy version. You can only add one rule at a time.

When adding a rule, use the index query parameter to set the position of the new rule within in the current list of rules. If you do not set this parameter, the new rule is added to the end of the current rule list. For Cloudlets, the first rule listed is the first rule evaluated.

{
    "matches": [
        {
            "matchType": "range",
            "objectMatchValue": {
                "type": "range",
                "value": [1, 25]
            },
            "matchOperator": "equals",
            "negate": false,
            "caseSensitive": false
        }
    ],
    "start": 0,
    "end": 0,
    "type": "asMatchRule",
    "disabled": "false",
    "forwardSettings": {
        "originId": "originremote2",
        "useIncomingQueryString": true,
        "pathAndQS": "/sales/Q1/"
    },
    "name": "Q1Sales",
    "id": null
}

{
    "location": "/cloudlets/api/v2/policies/1002/versions/2/rules/5db847a66e0566ad",
    "akaRuleId": "5db847a66e0566ad",
    "matches": [
        {
            "matchType": "range",
            "objectMatchValue": {
                "type": "range",
                "value": [1, 25]
            },
            "matchOperator": "equals",
            "negate": false,
            "caseSensitive": false
        }
    ],
    "start": 0,
    "end": 0,
    "type": "asMatchRule",
    "disabled": "false",
    "forwardSettings": {
        "originId": "originremote2",
        "useIncomingQueryString": true,
        "pathAndQS": "/sales/Q1/"
    },
    "name": "Q1Sales",
    "id": null
}

Get a version rule

Returns information about a specific rule within a policy version.

{
    "location": "/cloudlets/api/v2/policies/1002/versions/2/rules/5db847a66e0566ad",
    "akaRuleId": "5db847a66e0566ad",
    "matches": [
        {
            "matchType": "range",
            "objectMatchValue": {
                "type": "range",
                "value": [1, 25]
            },
            "matchOperator": "equals",
            "negate": false,
            "caseSensitive": false
        }
    ],
    "start": 0,
    "end": 0,
    "type": "asMatchRule",
    "disabled": "false",
    "forwardSettings": {
        "originId": "originremote2",
        "useIncomingQueryString": true,
        "pathAndQS": "/sales/Q1/"
    },
    "name": "Q1Sales",
    "id": null
}

Update a version rule

Updates attributes of an existing rule within a policy version.

When updating a rule, use the disabled member to prevent the rule from being evaluated against incoming requests.

{ "disabled": "true" }

{
    "location": "/cloudlets/api/v2/policies/1002/versions/2/rules/5db847a66e0566ad",
    "akaRuleId": "5db847a66e0566ad",
    "matches": [
        {
            "matchType": "range",
            "objectMatchValue": {
                "type": "range",
                "value": [1, 25]
            },
            "matchOperator": "equals",
            "negate": false,
            "caseSensitive": false
        }
    ],
    "start": 0,
    "end": 0,
    "type": "asMatchRule",
    "disabled": "true",
    "forwardSettings": {
        "originId": "originremote2",
        "useIncomingQueryString": true,
        "pathAndQS": "/sales/Q1/"
    },
    "name": "Q1Sales",
    "id": null
}

List associated properties

{
    "www.myproperty.com": {
        "groupId": 40498,
        "name": "www.myproperty.com",
        "newestVersion": {
            "activatedBy": "jsmith",
            "activationDate": "2015-08-25",
            "cloudletsOrigins": {
                "clorigin2": {
                    "id": "clorigin2",
                    "hostname": "origin2.myproperty.com",
                    "checksum": "0edc0bb1be7439248a77f48e806d2531",
                    "type": "CUSTOMER"
                },
                "clorigin1": {
                    "id": "clorigin1",
                    "hostname": "origin1.myproperty.com",
                    "checksum": "eefa90e680a1183725cfe2a1f00307c4",
                    "type": "CUSTOMER"
                }
            },
            "version": 5,
            "referencedPolicies": [
                "fr_policy_1"
            ]
        },
        "production": {
            "activatedBy": "jsmith",
            "activationDate": "2015-08-26",
            "cloudletsOrigins": {
                "clorigin2": {
                    "id": "clorigin2",
                    "hostname": "origin2.myproperty.com",
                    "checksum": "0edc0bb1be7439248a77f48e806d2531",
                    "type": "CUSTOMER"
                },
                "clorigin1": {
                    "id": "clorigin1",
                    "hostname": "origin1.myproperty.com",
                    "checksum": "eefa90e680a1183725cfe2a1f00307c4",
                    "type": "CUSTOMER"
                }
            },
            "version": 5,
            "referencedPolicies": [
                "fr_policy_1"
            ]
        },
        "staging": {
            "activatedBy": "sjones",
            "activationDate": "2015-08-25",
            "cloudletsOrigins": {
                "clorigin2": {
                    "id": "clorigin2",
                    "hostname": "origin2.myproperty.com",
                    "checksum": "0edc0bb1be7439248a77f48e806d2531",
                    "type": "CUSTOMER"
                },
                "clorigin1": {
                    "id": "clorigin1",
                    "hostname": "origin1.myproperty.com",
                    "checksum": "eefa90e680a1183725cfe2a1f00307c4",
                    "type": "CUSTOMER"
                }
            },
            "version": 5,
            "referencedPolicies": [
                "fr_policy_1"
            ]
        }
    }
}

Get associated properties for a policy

{
    "www.myproperty.com": {
        "groupId": 40498,
        "name": "www.myproperty.com",
        "newestVersion": {
            "activatedBy": "sjones",
            "activationDate": "2015-08-25",
            "cloudletsOrigins": {
                "clorigin2": {
                    "id": "clorigin2",
                    "hostname": "origin2.myproperty.com",
                    "checksum": "0edc0bb1be7439248a77f48e806d2531",
                    "type": "CUSTOMER"
                },
                "clorigin1": {
                    "id": "clorigin1",
                    "hostname": "origin1.myproperty.com",
                    "checksum": "eefa90e680a1183725cfe2a1f00307c4",
                    "type": "CUSTOMER"
                }
            },
            "version": 5,
            "referencedPolicies": [
                "fr_policy_1"
            ]
        },
        "production": {
            "activatedBy": "jsmith",
            "activationDate": "2015-08-26",
            "cloudletsOrigins": {
                "clorigin2": {
                    "id": "clorigin2",
                    "hostname": "origin2.myproperty.com",
                    "checksum": "0edc0bb1be7439248a77f48e806d2531",
                    "type": "CUSTOMER"
                },
                "clorigin1": {
                    "id": "clorigin1",
                    "hostname": "origin1.myproperty.com",
                    "checksum": "eefa90e680a1183725cfe2a1f00307c4",
                    "type": "CUSTOMER"
                }
            },
            "version": 5,
            "referencedPolicies": [
                "fr_policy_1"
            ]
        },
        "staging": {
            "activatedBy": "jsmith",
            "activationDate": "2015-08-25",
            "cloudletsOrigins": {
                "clorigin2": {
                    "id": "clorigin2",
                    "hostname": "origin2.myproperty.com",
                    "checksum": "0edc0bb1be7439248a77f48e806d2531",
                    "type": "CUSTOMER"
                },
                "clorigin1": {
                    "id": "clorigin1",
                    "hostname": "origin1.myproperty.com",
                    "checksum": "eefa90e680a1183725cfe2a1f00307c4",
                    "type": "CUSTOMER"
                }
            },
            "version": 5,
            "referencedPolicies": [
                "fr_policy_1"
            ]
        }
    }
}

List cloudlets origins

For this operation, you have the option of using the type query parameter to narrow the number of results returned by origin type. Options for the type parameter include APPLICATION_LOAD_BALANCER for Application Load Balancer origins, CUSTOMER for standard origins, and NETSTORAGE for NetStorage-based origins. You can use an APPLICATION_LOAD_BALANCER type to create a load balancing configuration.

NOTE: For Application Load Balancer, you can only use origins of type CUSTOMER for the data center origins. Origins with an origin type of APPLICATION_LOAD_BALANCER can support load balancing configurations.

[
    {
        "originId": "nsorigin1",
        "hostname": "download.akamai.com/12345",
        "checksum": "013c0cdefg7439248a77f48e806d2531",
        "type": "NETSTORAGE"
    },
    {
        "originId": "clorigin2",
        "hostname": "origin2.myproperty.com",
        "checksum": "eefa90cdefg9183725cfe2a1f00307c4",
        "type": "CUSTOMER"
    },
    {
        "originId": "alborigin1",
        "checksum": "abcdefg1111hijklmn22222fff76yae2",
        "description": "My super awesome ALB origin"
        "type": "APPLICATION_LOAD_BALANCER"
    }
]

Get a cloudlets origin

Run this operation to pull data about a specific Cloudlets Origin from the Property Manager API and into the Cloudlets API.

[
    {
        "originId": "clorigin1",
        "checksum": "abcdefg1111hijklmn22222fff76yae3",
        "description": "Origin for mobile user forwarding."
        "type": "APPLICATION_LOAD_BALANCER"
    }
]

Create a load balancing configuration

For Application Load Balancer, run this operation to create a load balancing configuration.

This operation is only available for the APPLICATION_LOAD_BALANCER origin type.

{
    "originId": "clorigin1",
    "checksum": "abcdefg1111hijklmn22222fff76yae3",
    "description": "Test load balancing configuration."
    "type": "APPLICATION_LOAD_BALANCER"
}

Update a load balancing configuration

For Application Load Balancer, run this operation to update the description of an existing load balancing configuration.

This operation is only available for the APPLICATION_LOAD_BALANCER origin type.

{
    "description": "Test load balancing configuration."
}

{
    "originId": "clorigin1",
    "checksum": "abcdefg1111hijklmn22222fff76yae3",
    "description": "Test load balancing configuration."
    "type": "APPLICATION_LOAD_BALANCER"
}

List load balancing versions

For Application Load Balancer, run this operation to list all versions of load balancing configuration.

The response lists the versions in descending order.

[
    {
        "createdBy": "jjones",
        "createdDate": "2016-03-08T11:42:18.690Z",
        "deleted": false,
        "description": "Test load balancing configuration.",
        "immutable": false,
        "lastModifiedBy": "ejnovak",
        "lastModifiedDate": "2016-06-02T00:40:02.237Z",
        "originId": "clorigin1",
        "version": 2
    },
    {
        "createdBy": "jjones",
        "createdDate": "2016-02-08T11:42:18.690Z",
        "deleted": false,
        "description": "Production load balancing configuration.",
        "immutable": false,
        "lastModifiedBy": "ejnovak",
        "lastModifiedDate": "2016-05-02T00:40:02.237Z",
        "originId": "clorigin1",
        "version": 1
    }
]

Create a load balancing version

You can create multiple versions of the load balancing configuration. By versioning these settings, you can test new configurations, or manage changes to the data centers supporting Application Load Balancer.

Only Cloudlets Origins with an originType of APPLICATION_LOAD_BALANCER can support load balancing configurations.

The liveness test for Application Load Balancer uses a basic HTTP poll.

{
    "balancingType": "WEIGHTED",
    "dataCenters": [
        {
            "cloudService": false,
            "livenessHosts": [
                "clorigin3.www.example.com",
            ],
            "latitude": 102.78108,
            "longitude": -116.07064,
            "continent": "NA",
            "country": "US",
            "originId": "clorigin3",
            "percent": 100.0
        }
    ],
    "deleted": false,
    "description": "Test load balancing configuration.",
    "immutable": false,
    "livenessSettings": {
        "hostHeader": "clorigin3.www.example.com",
        "interval": 25,
        "path": "/status",
        "port": 443,
        "protocol": "HTTPS",
        "status3xxFailure": false,
        "status4xxFailure": true,
        "status5xxFailure": false,
        "timeout": 30
    },
    "originId": "clorigin3",
    "version": 4
}

{
    "balancingType": "WEIGHTED",
    "createdBy": "jjones",
    "createdDate": "2015-10-08T11:42:18.690Z",
    "dataCenters": [
        {
            "cloudService": false,
            "livenessHosts": [
                "clorigin3.www.example.com",
            ],
            "latitude": 102.78108,
            "longitude": -116.07064,
            "continent": "NA",
            "country": "US",
            "originId": "clorigin3",
            "percent": 100.0
        }
    ],
    "deleted": false,
    "description": "Test load balancing configuration."
    "immutable": false,
    "lastModifiedBy": "ejnovak",
    "lastModifiedDate": "2016-05-02T00:40:02.237Z",
    "livenessSettings": {
        "hostHeader": "clorigin3.www.example.com",
        "interval": 25,
        "path": "/status",
        "port": 443,
        "protocol": "HTTPS",
        "status3xxFailure": false,
        "status4xxFailure": true,
        "status5xxFailure": false,
        "timeout": 30
    },
    "originId": "clorigin3",
    "version": 4
}

Get a load balancing version

For this operation, you have the option of using the validate query parameter. When set to true, this parameter verifies whether the settings for the selected originId and version are valid. The default setting for this parameter is false.

{
    "balancingType": "WEIGHTED",
    "createdBy": "jjones",
    "createdDate": "2015-10-08T11:42:18.690Z",
    "dataCenters": [
        {
            "cloudService": false,
            "livenessHosts": [
                "clorigin3.www.example.com",
            ],
            "latitude": 102.78108,
            "longitude": -116.07064,
            "continent": "NA",
            "country": "US",
            "originId": "clorigin3",
            "percent": 100.0
        }
    ],
    "deleted": false,
    "description": "Cloudlets origin for ALB rollout.",
    "immutable": false,
    "lastModifiedBy": "ejnovak",
    "lastModifiedDate": "2016-05-02T00:40:02.237Z",
    "livenessSettings": {
        "hostHeader": "clorigin3.www.example.com",
        "interval": 25,
        "path": "/status",
        "port": 443,
        "protocol": "HTTPS",
        "status3xxFailure": false,
        "status4xxFailure": true,
        "status5xxFailure": false,
        "timeout": 30
    },
    "originId": "clorigin1",
    "version": 4
}

Update a load balancing version

You cannot edit a load balancing configuration version that has ever been activated.

{
    "balancingType": "WEIGHTED",
    "dataCenters": [
        {
            "cloudService": false,
            "latitude": 102.78108,
            "longitude": -116.07064,
            "continent": "NA",
            "country": "US",
            "originId": "clorigin3",
            "percent": 100.0
        }
    ],
    "deleted": false,
    "description": "Cloudlets origin for ALB rollout.",
    "livenessSettings": {
        "path": "/status",
        "port": 443,
        "protocol": "HTTPS",
        "status3xxFailure": false,
        "status4xxFailure": true,
        "status5xxFailure": false
    },
    "originId": "clorigin1",
    "version": 4
}

{
    "balancingType": "WEIGHTED",
    "createdBy": "jjones",
    "createdDate": "2015-10-08T11:42:18.690Z",
    "dataCenters": [
        {
            "cloudService": false,
            "livenessHosts": [
                "clorigin3.www.example.com",
            ],
            "latitude": 102.78108,
            "longitude": -116.07064,
            "continent": "NA",
            "country": "US",
            "originId": "clorigin3",
            "percent": 100.0
        }
    ],
    "deleted": false,
    "description": "Test load balancing configuration.",
    "immutable": false,
    "lastModifiedBy": "ejnovak",
    "lastModifiedDate": "2016-05-02T00:40:02.237Z",
    "livenessSettings": {
        "hostHeader": "clorigin3.www.example.com",
        "interval": 25,
        "path": "/status",
        "port": 443,
        "protocol": "HTTPS",
        "status3xxFailure": false,
        "status4xxFailure": true,
        "status5xxFailure": false,
        "timeout": 30
    },
    "originId": "clorigin1",
    "version": 4
}

List current load balancing activations

{
    "clorigin1": {
        "PRODUCTION": {
            "activatedBy": "jjones",
            "activatedDate": "2016-04-07T18:41:34.251Z",
            "network": "PRODUCTION",
            "originId": "clorigin1",
            "status": "active",
            "version": 1
        },
        "STAGING": {
            "activatedBy": "ejnovak",
            "activatedDate": "2016-05-30T18:41:34.251Z",
            "network": "PRODUCTION",
            "originId": "clorigin1",
            "status": "active",
            "version": 2
        }
    },
    "clorigin2": {
        "STAGING": {
            "activatedBy": "gzhang",
            "activatedDate": "2016-02-03T18:41:34.391Z",
            "network": "STAGING",
            "originId": "clorigin2",
            "status": "active",
            "version": 1
        }
    }
}

List activations for a load balancing configuration

The response lists the activations by the activatedDate with the most recent listed first.

[
    {
        "activatedBy": "jjones",
        "activatedDate": "2016-05-03T18:41:34.251Z",
        "network": "PRODUCTION",
        "originId": "clorigin1",
        "status": "active",
        "version": 1
    },
    {
        "activatedBy": "ejnovak",
        "activatedDate": "2016-04-07T18:41:34.461Z",
        "network": "STAGING",
        "originId": "clorigin1",
        "status": "active",
        "version": 2
    }
]

Activate a load balancing version

{
    "network": "STAGING",
    "dryrun": false,
    "version": 1
}

[
    {
        "activatedBy": "jjones",
        "activatedDate": "2016-04-07T18:41:34.251Z",
        "network": "PRODUCTION",
        "originId": "clorigin1",
        "status": "active",
        "dryrun": false,
        "version": 1
    }
]

List policy activations

Returns the complete activation history for the selected policy in reverse chronological order.

For this operation, you have the option of using the network and the propertyName query parameters to narrow the number of results returned. If using the network parameter, you can enter either staging or production. For the propertyName parameter, you need to know the name of the property associated with the Cloudlets policy versions you want a list of.

[
    {
    "serviceVersion": null,
    "apiVersion": "2.0",
    "network": "staging",
    "policyInfo":
        {
            "policyId": 2962,
            "name": "RequestControlPolicy",
            "version": 1,
            "status": "ACTIVE",
            "statusDetail": "File successfully deployed to Akamai's network",
            "detailCode": 4000,
            "activationDate": 1427428800000,
            "activatedBy": "jsmith"
        },
    "propertyInfo":
        {
            "name": "www.rc-cloudlet.com",
            "version": 0,
            "groupId": 40498,
            "status": "INACTIVE",
            "activatedBy": null,
            "activationDate": 0
        }
    }
]

Activate a policy version

Activate the selected cloudlet policy version. After activation completes, the Cloudlets policy is ready for use.

You can activate a policy version with a POST operation against the ../policies/{version}/activations endpoint, if you include the network and version JSON members.

If you include the network attribute in the request body, you can also activate a policy version by issuing a POST to the /cloudlets/api/v2/policies/{policyId}/versions/{version}/activations endpoint.

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

The property activation status is either active or inactive.

NOTE: If you are using NetStorage, review the NetStorage Activation Considerations section.

Get a schema

Get a JSON schema for interacting with policies to validate different requests used with this API.

For the request’s schemaName, use one the following, where cloudletType corresponds to the cloudletCode available from List Cloudlets.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "CREATE POLICY",
    "description": "applied to requests to create policies of the form: POST /cloudlets/api/v2/policies",
    "version" : "1.0",
    "location" : "/cloudlets/api/v2/schemas/create-policy.json",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "pattern": "^[a-z_A-Z0-9]+$",
            "maxLength": 64
        },
        "cloudletId": {
            "type": "integer",
            "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8 ]
        },
        "description": {
            "type": [ "string", "null" ],
            "maxLength": 255
        },
        "propertyName": {
            "type": [ "string", "null" ],
            "pattern": "^[a-z_A-Z0-9\\.\\-]+$"
        },
        "groupId": {
            "type": "integer"
        }
    },
    "required": [ "cloudletId", "name" ],
    "additionalProperties": false
}

List schemas per Cloudlet

Get links to all the JSON schemas by Cloudlet type (cloudletCode) to validate different requests used with this API. See List Cloudlets for information on how to obtain the cloudletCode.

{
    "schemas":
    [{
        "title": "EDGE REDIRECTOR MATCH RULE",
        "version": "1.0",
        "location": "/cloudlets/api/v2/schemas/match_rule-ER-1.0.json",
        "description": "applied to create/update match rule requests for ER cloudlets, where requests are of the form: POST|PUT /api/v2/policies/{policyId}/versions/{versionId}/rules/{ruleId}",
         "additionalDescription": "null"
    },
    {
        "title": "CREATE/CLONE POLICY VERSION",
        "version": "1.0",
        "location": "/cloudlets/api/v2/schemas/create-nimbus_policy_version-ER-1.0.json",
        "description": "applied to create/clone policy version requests of form: POST /policies/{policyId}/versions ",
        "additionalDescription": "applied to policy version requests for ER cloudlets"
    },
    {
        "title": "UPDATE POLICY VERSION",
        "version": "1.0",
        "location": "/cloudlets/api/v2/schemas/update-nimbus_policy_version-ER-1.0.json",
        "description": "applied to update policy version requests of form: PUT /policies/{policyId}/versions/{versionId} ",
        "additionalDescription": "applied to policy version requests for ER cloudlets"
    },
    {
        "title": "CREATE POLICY",
        "version": "1.0",
        "location": "/cloudlets/api/v2/schemas/create-policy.json",
        "description": "applied to requests to create policies of the form: POST /cloudlets/api/v2/policies",
        "additionalDescription": "null"
    },
    {
        "title": "UPDATE POLICY",
        "version": "1.0",
        "location": "/cloudlets/api/v2/schemas/update-policy.json",
        "description": "applied to all requests to update policies of the form: PUT /cloudlets/api/v2/policies/{policyId}",
        "additionalDescription": "null"
    },
    {
        "title": "CLONE POLICY",
        "version": "1.0",
        "location": "/cloudlets/api/v2/schemas/clone-policy.json",
        "description": "applied to requests to clone policies of the form: POST /cloudlets/api/v2/policies?clonePolicyId=***",
        "additionalDescription": "null"
    }]
}

Data

This section shows you the data model for the Cloudlets v2 API. The sections are organized based the standard workflow through this API.

In addition, JSON schemas are available for this API. See the JSON Schemas section for a list of schemas.

NOTE: See the Matches section for information about properties available for match rules.

CloudletInfo

The Cloudlet object (CloudletInfo) provides data about the Cloudlets enabled for an account.

When retrieving data for a single Cloudlet, the cloudletId is required. This property is returned when you run a GET for all Cloudlet information.

Sample GET response:

[
   {
      "apiVersion" : "2.0",
      "cloudletCode" : "FR",
      "cloudletId" : 3,
      "cloudletName" : "FORWARDREWRITE",
      "location" : "/api/v2/cloudlet-info/3",
      "serviceVersion" : null
   },
   {
      "apiVersion" : "2.0",
      "cloudletCode" : "ER",
      "cloudletId" : 0,
      "cloudletName" : "EDGEREDIRECTOR",
      "location" : "/api/v2/cloudlet-info/0",
      "serviceVersion" : null
   }
]

A 200 response message indicates the network successfully processed the request.

See HTTP Codes for a list of status codes returned with this API.

CloudletInfo members

GroupInfo

The Group-Level Cloudlet object (GroupInfo) provides data about the types of Cloudlets associated with the groups you have edit privileges for. This object supports GET requests that retrieve data either for all groups containing Cloudlets, or for a specific group.

When retrieving data for a single group, the groupId is required. Use -1 to request policies from your default group. The groupId is returned when you run a GET for all group information. For results to display, however, you must have edit privileges for one or more Cloudlet types within the group.

Sample GET response:

[
   {
      "apiVersion" : "2.0",
      "capabilities" : [
         {
            "capabilities" : [
               "View",
               "Edit",
               "Activate"
            ],
            "cloudletCode" : "ER",
            "cloudletId" : 0
         }
      ],
      "groupId" : 5678,
      "groupName" : "Subgroup 1",
      "location" : "/api/v2/group-info/5678",
      "parentId" : 1234,
      "properties" : ["www.example.com", "www.example.org"],
      "serviceVersion" : null
   }
]

GroupInfo members

GroupInfo.capabilities[]  

Policy

The Cloudlet Policy object (Policy) allows you to create and manage your Cloudlet policies. When creating a Cloudlet policy, your request needs to include both the cloudletId (like 0 for Edge Redirector) and the groupId for the Cloudlet you are configuring. In addition, a name for the policy and a description are required.

Within a Cloudlet policy you set up specific versions, and within these versions you set up the match rules for governing how the Cloudlet is used.

Request and response examples

To create a new policy, you POST to the same endpoint from which you GET your full set of properties.

Sample GET response:

{
   "activations" : [
      {
         "apiVersion" : "2.0",
         "network" : "prod",
         "policyInfo" : {
            "activatedBy" : null,
            "activationDate" : 0,
            "detailCode" : 0,
            "name" : "TestCreatePolicy1",
            "policyId" : 1002,
            "status" : "INACTIVE",
            "version" : 0
         },
         "propertyInfo" : null,
         "serviceVersion" : null
      },
      {
         "apiVersion" : "2.0",
         "network" : "staging",
         "policyInfo" : {
            "activatedBy" : null,
            "activationDate" : 0,
            "detailCode" : 0,
            "name" : "TestCreatePolicy1",
            "policyId" : 1002,
            "status" : "INACTIVE",
            "version" : 0
         },
         "propertyInfo" : null,
         "serviceVersion" : null
      }
   ],
   "apiVersion" : "2.0",
   "cloudletCode" : "CC",
   "cloudletId" : 99,
   "createDate" : 1428957069841,
   "createdBy" : "jsmith",
   "deleted" : false,
   "description" : "Creating a policy",
   "groupId" : 1234,
   "lastModifiedBy" : "jsmith",
   "lastModifiedDate" : 1428957069841,
   "location" : "/api/v2/policies/1002",
   "name" : "CreatePolicy1",
   "policyId" : 1002,
   "propertyName" : null,
   "serviceVersion" : null
}

A 200 response message indicates the network successfully processed the request. A 201 response message indicates that a policy was successfully created.

See HTTP Codes for a list of status codes returned with this API.

Policy members

Policy.activations[]  

PolicyVersion

The Cloudlets Policy Version object (PolicyVersion) allows you to create and manage versions of your Cloudlet policies.

Sample GET response:

{
   "activations" : [
      {
         "apiVersion" : "2.0",
         "network" : "prod",
         "policyInfo" : {
            "activatedBy" : null,
            "activationDate" : 0,
            "detailCode" : 0,
            "name" : "CreatePolicy1",
            "policyId" : 1002,
            "status" : "INACTIVE",
            "version" : 2
         },
         "propertyInfo" : null,
         "serviceVersion" : null
      },
      {
         "apiVersion" : "2.0",
         "network" : "staging",
         "policyInfo" : {
            "activatedBy" : null,
            "activationDate" : 0,
            "detailCode" : 0,
            "name" : "CreatePolicy1",
            "policyId" : 1002,
            "status" : "INACTIVE",
            "version" : 2
         },
         "propertyInfo" : null,
         "serviceVersion" : null
      }
   ],
   "createDate" : 1428957891084,
   "createdBy" : "sjones",
   "description" : "New version of forwarding policy.",
   "lastModifiedBy" : "jsmith",
   "lastModifiedDate" : 1428957891084,
   "matchRules" : [],
   "policyId" : 1002,
   "revisionId" : 12345,
   "rulesLocked" : false,
   "version" : 2
}

PolicyVersion members

PolicyVersion.activations[]  

PropertyAssociation

Use the Property Association object (PropertyAssociation) to find out which versions of a property that is associated with a Cloudlets policy is activated on the production and staging networks.

Sample GET response:

{
    "www.myproperty.com": {
        "groupId": 40498,
        "name": "www.myproperty.com",
        "newestVersion": {
            "activatedBy": "sjones",
            "activationDate": "2015-08-25",
            "cloudletsOrigins": {
                "nsorigin1": {
                    "id": "nsorigin1",
                    "hostname": "origin2.myproperty.com",
                    "checksum": "0edc0bb1be7439248a77f48e806d2531",
                    "type": "NETSTORAGE"
                },
                "clorigin1": {
                    "id": "clorigin1",
                    "hostname": "origin1.myproperty.com",
                    "checksum": "eefa90e680a1183725cfe2a1f00307c4",
                    "type": "CUSTOMER"
                }
            },
            "version": 5,
            "referencedPolicies": ["fr_policy_1"]
        },
        "production": {
            "activatedBy": "jsmith",
            "activationDate": "2015-08-26",
            "cloudletsOrigins": {
                "clorigin2": {
                    "id": "clorigin2",
                    "hostname": "origin2.myproperty.com",
                    "checksum": "0edc0bb1be7439248a77f48e806d2531",
                    "type": "NETSTORAGE"
                },
                "clorigin1": {
                    "id": "clorigin1",
                    "hostname": "origin1.myproperty.com",
                    "checksum": "eefa90e680a1183725cfe2a1f00307c4",
                    "type": "CUSTOMER"
                }
            },
            "version": 5,
            "referencedPolicies": ["fr_policy_1"]
        },
        "staging": {
            "activatedBy": "jsmith",
            "activationDate": "2015-08-25",
            "cloudletsOrigins": {
                "nsorigin1": {
                    "id": "nsorigin1",
                    "hostname": "origin2.myproperty.com",
                    "checksum": "0edc0bb1be7439248a77f48e806d2531",
                    "type": "NETSTORAGE"
                },
                "clorigin1": {
                    "id": "clorigin1",
                    "hostname": "origin1.myproperty.com",
                    "checksum": "eefa90e680a1183725cfe2a1f00307c4",
                    "type": "CUSTOMER"
                }
            },
            "version": 5,
            "referencedPolicies": ["fr_policy_1"]
        }
    }
}

PropertyAssociation members

At the top level of the PropertyAssociation object is an arbitrary key that corresponds to the name of a property associated with one or more Cloudlets policies. This property may or may not have Cloudlets Origins configured on it.

This top-level object includes additional objects containing information about the latest version of the property, as well as its status on the production and staging environments. See PropertyAssociation.* below for a description of its members.

PropertyAssociation.*

PropertyAssociation.*.*

PropertyAssociation.*.*.cloudletsOrigins.*

CloudletsOrigin for Application Load Balancer

For the Application Load Balancer Cloudlet, use the Cloudlets Origin object (CloudletsOrigin) to view information about all types of Cloudlets Origins, and to set up and maintain load balancing configurations.

Load balancing configurations require a Cloudlets Origin with an originType of APPLICATION_LOAD_BALANCER.

NOTE: The /cloudlets/api/v2/conditional-origins?{policyId} endpoint that was previously used for Cloudlets Origins has been deprecated. See the Property Association Operations section for operations that return information about Cloudlets Origins.

Sample GET response:

[
    {
        "originId": "clorigin1",
        "checksum": "abcdefg1111hijklmn22222fff76yae3",
        "description": "Test load balancing configuration."
        "type": "APPLICATION_LOAD_BALANCER"
    }
]

CloudletsOrigin members

LoadBalancingVersion

The Load Balancing Version (LoadBalancingVersion) object allows you to set up and maintain separate versions of load balancing configurations associated with a Cloudlets Origin. Only Cloudlets Origins with an originType of APPLICATION_LOAD_BALANCER support load balancing versions.

Sample GET response:

{
    "balancingType": "WEIGHTED",
    "createdBy": "jjones",
    "createdDate": "2015-10-08T11:42:18.690Z",
    "dataCenters": [
        {
            "cloudService": false,
            "livenessHosts": [
                "clorigin3.www.example.com",
            ],
            "latitude": 102.78108,
            "longitude": -116.07064,
            "continent": "NA",
            "country": "US",
            "originId": "clorigin3",
            "percent": 100.0
        }
    ],
    "deleted": false,
    "description": "Initial load balancing configuration for ALB rollout.",
    "immutable": false,
    "lastModifiedBy": "ejnovak",
    "lastModifiedDate": "2016-05-02T00:40:02.237Z",
    "livenessSettings": {
        "hostHeader": "clorigin3.www.example.com",
        "interval": 25,
        "path": "/directory/subdirectory",
        "port": 443,
        "protocol": "HTTPS",
        "status3xxFailure": false,
        "status4xxFailure": true,
        "status5xxFailure": false,
        "timeout": 30
    },
    "originId": "clorigin1",
    "version": 4
}

LoadBalancingVersion members

LoadBalancingVersion.dataCenters[]  

LoadBalancingVersion.livenessSettings

LoadBalancingVersionActivations

For the Application Load Balancer Cloudlet, use the Load Balancing Version Activation object (LoadBalancingVersionActivations) to activate a specific load balancing version on the network you select. Only Cloudlets Origins with an originType of APPLICATION_LOAD_BALANCER can support load balancing configurations.

Sample GET response:

[
    {
        "activatedBy": "jjones",
        "activatedDate": "2016-04-07T18:41:34.251Z",
        "network": "PRODUCTION",
        "originId": "clorigin1",
        "status": "active",
        "dryrun": false,
        "version": 1
    }
]

LoadBalancingVersion.activations

Policy Activation

To use the Activation object (Activation), you need to know the version of the policy you want to activate or view. The version member, which is returned with policy version operations, provides this information.

Sample GET response:

[
    {
        "serviceVersion": null,
        "apiVersion": "2.0",
        "network": "staging",
        "policyInfo": {
            "policyId": 3235,
            "name": "sampleERpolicy",
            "version": 2,
            "status": "pending",
            "statusDetail": "batched",
            "detailCode": 1000,
            "activatedBy": "sjones",
            "activationDate": 1444929490000
        },
        "propertyInfo": {
            "name": "app_cloudlets.xml",
            "version": 1,
            "groupId": 40498,
            "status": "deactivated",
            "activatedBy": "jsmith",
            "activationDate": 1410825600000
        }
    }
]

Activation members

Activation.policyInfo

Activation.propertyInfo

JSON schemas

The following JSON Schemas are available for this API:

Sample GET response:

{
    "schemas": [
        {
            "title": "EDGE REDIRECTOR MATCH RULE",
            "version": "1.0",
            "location": "/api/v2/schemas/match_rule-ER-1.0.json",
            "description": "applied to create/update match rule requests for ER cloudlets, where requests are of the form: POST|PUT /api/v2/policies/{policyId}/versions/{versionId}/rules/{ruleId}",
            "additionalDescription": "null"
        },
        {
            "title": "CREATE/CLONE POLICY VERSION",
            "version": "1.0",
            "location": "/api/v2/schemas/create-nimbus_policy_version-ER-1.0.json",
            "description": "applied to create/clone policy version requests of form: POST /policies/{policyId}/versions ",
            "additionalDescription": "applied to policy version requests for ER cloudlets"
        },
        {
            "title": "UPDATE POLICY VERSION",
            "version": "1.0",
            "location": "/api/v2/schemas/update-nimbus_policy_version-ER-1.0.json",
            "description": "applied to update policy version requests of form: PUT /policies/{policyId}/versions/{versionId} ",
            "additionalDescription": "applied to policy version requests for ER cloudlets"
        },
        {
            "title": "CREATE POLICY",
            "version": "1.0",
            "location": "/api/v2/schemas/create-policy.json",
            "description": "applied to requests to create policies of the form: POST /cloudlets/api/v2/policies",
            "additionalDescription": "null"
        },
        {
            "title": "UPDATE POLICY",
            "version": "1.0",
            "location": "/api/v2/schemas/update-policy.json",
            "description": "applied to all requests to update policies of the form: PUT /cloudlets/api/v2/policies/{policyId}",
            "additionalDescription": "null"
        },
        {
            "title": "CLONE POLICY",
            "version": "1.0",
            "location": "/api/v2/schemas/clone-policy.json",
            "description": "applied to requests to clone policies of the form: POST /cloudlets/api/v2/policies?clonePolicyId=***",
            "additionalDescription": "null"
        }
    ]
}

Schema members

Match rules

Once a Cloudlet policy has been created, you can then add match rules to an existing version of that policy, or when you create a new policy version.

NOTE: The maximum number of rules per Cloudlets policy is currently 5,000. However, there is no limit to the number of Cloudlets policies you can create.

Working with match rules

When working with Cloudlets match rules, all of the match criteria are included in the matchRules array.

Within the matchRules array, it is common to use the matches array, which defines potential conditions, like case sensitivity (caseSensitive) or the type of match (matchType). These properties apply to all Cloudlets.

You use the matchType properties to set up the part of the request that the rule applies to, like redirect URL (matchURL) or path and query string (pathAndQS).

For additional examples, see Cloudlet-Specific Match Examples.

When a Cloudlet executes, the first rule applied is the first one that is true based on criteria in the incoming request.

Match rule considerations

When setting up rules for Cloudlets, be aware of the following:

• There is currently no way to implement an else case in a rule.

• There are no child rules within Cloudlet policies.

• When a new policy is created, version 1 of the policy is also created. This version is empty: it contains neither a description nor any match rules (matchRules).

• If you clone an existing policy, the matchRules for version 1 of the new policy are copied from the most recent version of the cloned policy.

Match rule versions

When setting up the rules for a Cloudlet policy version, you first need to determine the matchRuleFormat to use. The matchRuleFormat attribute indicates the version of the Cloudlet-specific matchRules JSON, and uses the following format: {major}.{minor}. The major number always matches the value in the URI pathname (.../api/{version}/...). The current major version is 2. The minor number changes as attributes are added to or removed from the resource objects.

NOTE: If you issue a PUT or POST request for Cloudlet policy versions that include matchRules, you also need to use the matchRuleFormat property.

Locking rules

The rulesLocked property is automatically set to true when a policy version is activated on a network. When rulesLocked equals true, the policy version’s rules can no longer be edited. No further PUTs are allowed against the policy version.

If the rules are locked for a policy version, you must create a new policy version to continue editing the policy.

NOTE: If desired, use the cloning parameter, cloneVersion, to edit the policy.

Matching with wildcards

You can use wildcard characters (* and ?) for the following match types: cookie, header, path, extension, filename, query, and hostname.

NOTE: The cookie and query matches only accept wildcards for the value, not the cookie or query name. For example, "matchValue":"cookiename=m*nster" would be valid, but "matchValue":"c*kiename=m*nster" would not.

As a wildcard, the asterisk represents zero or more characters in a string of characters, and the question mark represents a single character.

With the exception of hostname, when using a wildcard with this API, you need to set the matchOperator parameter to contains. For hostname, the contains setting is not required. If you enter an asterisk in the hostname property, it is automatically treated as a wildcard.

Wildcard match example

In the following example, the first match listed uses a wildcard: the matchvalue of /products/wildcards/*.jpg matches on any .jpg file in the /products/wildcards/ directory. This is because the matchOperator is contains.

The second match, however, literally looks for a file called *.jpg because the matchOperator is equals.

{
    "matchRules": [{
        "matchURL": null,
        "matches": [{
            "matchType": "path",
            "matchValue": "/products/wildcards/*.jpg",
            "matchOperator": "contains",
            "negate": false,
            "caseSensitive": false
        },
        {
            "matchType": "path",
            "matchValue": "/products/literals/*.jpg",
            "matchOperator": "equals",
            "negate": false,
            "caseSensitive": false
        },
        "start": 0,
        "end": 0,
        "type": "apMatchRule",
        "useIncomingQueryString": false,
        "passThroughPercent": "50",
        "name": "RequiredNameField",
        "id": null
}

Matching with regular expressions

For the Audience Segmentation, Edge Redirector, Forward Rewrite, and Input Validation Cloudlets, you can now use regular expressions to match on the fully qualified incoming request URL.

The regular expression can be up to 256 characters. If your regular expression includes any characters that have a special use in regular expressions (like ., +, or ?), you must use a backslash (\) to escape each special character.

For Cloudlets, RE2 is supported. RE2 is a library for regular expressions with a C++ interface that uses the finite-state machine (FSM) computational model. Go to Google’s re2 repository or a similar site, for information about RE2’s syntax.

For Edge Redirector, you can also use the information from capture groups in regular expressions to form the redirect URL. For Audience Segmentation and Forward Rewrite you can use the information from capture groups in regular expressions to form the forward path and, if desired, the query string. Input Validation does not support capture groups.

Capture groups allow you to capture incoming information from the source URL, while substitution patterns allow you to refer to those capture groups in the modified URL. Substitution patterns use the backslash character (\) followed by a number to refer to the capture groups. For example, \1 is the first capture group, \2 is the second, etc.

NOTE: The regular expressions match for Cloudlets supports a maximum of nine numbered substitutions using capture groups.

Regular expression match example

The following is an example of a Forward Rewrite match rule that contains a regular expression.

{
    "matchRules": [
        {
            "matches": [
                {
                    "matchType": "regex",
                    "matchValue": "^https?://(?:[A-z0-9|\\.]*)/(.*)",
                    "matchOperator": "equals",
                    "negate": false,
                    "caseSensitive": false
                }
            ],
            "start": 0,
            "end": 0,
            "type": "frMatchRule",
            "forwardSettings": {
                "pathAndQS": "/\\1&extra_param=bar",
                "useIncomingQueryString": false
            },
            "id": null
        }
    ],
    "matchRuleFormat": "1.0",
    "rulesLocked": false
}

In this example, the regular expression value is ^https?://(?:[A-z0-9|\.]*)/(.*) and the forward path and query string value containing a substitution pattern is /\1&extra_param=bar. When this rule is activated, all requests to http://www.example.com/path1/path2/home.html?query=foo would retrieve content from http://www.example.com/path1/path2/home.html?query=foo&extra_param=bar without changing the URL.

Match types that support multiple values

The following matchType properties support multiple space-separated values (not names): extension, hostname, path, and query. When setting up a rule using these match types, you can accidentally create a rule that never matches a request, like the following:

        "matches": [
            {
                "matchType": "query",
                "matchValue": "p=x",
                "matchOperator": "equals",
                "negate": false,
                "caseSensitive": false
            }
            {
                "matchType": "query",
                "matchValue": "p=y",
                "matchOperator": "equals",
                "negate": false,
                "caseSensitive": false
            }
        ],

The separate match conditions in this example do not work because the incoming request has to have both p=x and p=y, which is not valid. However, if matchValue:"p=x y", it means a match occurs if either p=x or p=y is in the incoming request.

Matches in requests and responses

When adding match rule criteria to the JSON request for a POST or PUT operation on the /policies/{nnnn}/versions/{n} endpoint, you set up the matchRules array after defining the matchRuleFormat. Here, for example, is a PUT request that adds an Edge Redirector rule with matches based on the incoming request header:

{
   "description" : "Edge Redirector Header Rules",
   "matchRuleFormat" : "1.0",
   "matchRules" : [
        {
        "type": "erMatchRule",
        "end": 1403127780,
        "id": 0,
        "matches": [
            {
            "matchOperator": "contains",
            "matchType": "header",
            "objectMatchValue": {
                "type": "object",
                "name": "contentType",
                "nameCaseSensitive": false,
                "nameHasWildcard": false,
                "options": {
                    "value": [
                        "text/html*",
                        "text/css*",
                        "application/x-javascript*"
                    ],
                    "valueHasWildcard": true,
                    "valueCaseSensitive": false
                }
            }
        },
        {
            "matchOperator": "exists",
            "matchType": "header",
            "objectMatchValue": {
                "type": "object",
                "name": "Cache-Control",
                "nameCaseSensitive": false,
                "nameHasWildcard": false
            },
            "negate": false
        }
    ],
    "name": rule1,
    "redirectURL": "http://www.redirect.com",
    "start": 1403041407,
    "statusCode": 301,
    "useIncomingQueryString": false
}

NOTE: The response includes the same match information you provided in the request.

Match properties

This section provides information on the various types of properties used with Cloudlets match rules.

Match rules properties

The Match Rules (matchRules) array contains all of your rules and includes the following properties, which vary based on the Cloudlet you are using:

Match conditions properties

Each object within the matches array defines potential conditions, like case sensitivity (caseSensitive) or the type of match (matchType). These properties apply to all Cloudlets.

A matches property contains an array of objects with the following properties/conditions:

Match value object properties

The following table lists the properties available for the objectMatchValue object:

Match type property

The matchType properties provide information about the match types used to conditionally pass through the request.

NOTE: Match types with an “m” support multiple space-separated values (not names).

Device characteristics match values

The following values are available for the deviceCharacteristics match type:

Supported match types by Cloudlet

The following table lists, by Cloudlet, the supported match types:

Cloudlet-specific match examples

For each of the following Cloudlets, this section provides match rule examples:

• Application Load Balancer
• API Prioritization
• Audience Segmentation
• Cloud Marketing
• Cloud Marketing Plus
• Edge Redirector
• Forward Rewrite
• Input Validation
• Phased Release
• Request Control
• Visitor Prioritization

Application Load Balancer

The Application Load Balancer Cloudlet 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.

Match rule example

For the following Application Load Balancer match rule, any URL that uses the HTTP protocol, has a domain name of source.com, and includes test=null as a query string is sent to the appropriate data center based on the load balancing settings.

{
    "matchRules": [{
        "type": "albMatchRule",
        "matches": [{
            "caseSensitive": false,
            "matchOperator": "contains",
            "matchType": "protocol",
            "matchValue": "http",
            "negate": false
        },
        {
            "caseSensitive": false,
            "matchOperator": "contains",
            "matchType": "query",
            "matchValue": "test=null",
            "negate": false
        }],
        "name": "rule 1",
        "disabled": false,
        "forwardSettings":{"originId":"ALBOrigin_1"},
        "useIncomingQueryString": false
    }]
}

API Prioritization

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.

Match rule example

For this example, if the incoming URL has an extension of .jsp, 50% of the time the static response is served.

{
    "matchRules": [{
        "matchURL": null,
        "matches": [{
            "matchType": "extension",
            "matchValue": "jsp",
            "matchOperator": "equals",
            "negate": false,
            "caseSensitive": false
            }],
        "start": 0,
        "end": 0,
        "disabled": false,
        "type": "apMatchRule",
        "useIncomingQueryString": false,
        "passThroughPercent": "50",
        "name": "RequiredNameField",
        "id": null
    }]
}

Audience Segmentation

Audience Segmentation provides traffic segmentation and stickiness without degrading performance, which is often beneficial for A/B and multivariate testing. This Cloudlet creates stable test populations by assigning a cookie value to the user based on the rules you define.

This Cloudlet supports a range match. When setting up a range match, enter the two numbers that comprise the range. If the random value assigned to an incoming request falls within this range (inclusive), the match is true.

NOTE: You can only include one Range Match per rule.

Match rule example

For this example, if the incoming request is assigned a value between 1 and 25 (inclusive), the request is forwarded to the /sales/Q1 directory. Any query strings from the incoming request is appended to the forward request URL.

{
    "matchRules": [{
        "matches": [{
            "matchType": "range",
            "objectMatchValue": {"type": "range","value": [1,25]},
            "matchOperator": "equals","negate": false,"caseSensitive": false}],
        "start": 0,
        "end": 0,
        "disabled": false,
        "type": "asMatchRule",
        "forwardSettings": {
            "originId": "originremote2",
            "useIncomingQueryString": true,
            "pathAndQS": "/sales/Q1/"},
        "name": "Q1SalesTestPop",
        "id": null
    }]
}

Cloud Marketing

If you are a MediaMath customer, Cloud Marketing 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.

Match rule example

For this match rule, if the incoming URL includes /content/sales/ in its path, then the MediaMath JavaScript tags are added to the requested page.

{
    "matchRules": [{
        "name": "JS_Insertion_for_Sales",
        "type": "mmbMatchRule",
        "start": 0,
        "end": 0,
        "id": 0,
        "matchURL": null,
        "matches": [{
            "caseSensitive": false,
            "matchOperator": "contains",
            "matchType": "path",
            "matchValue": "/content/sales/",
            "negate": false
        }],
        "jsInsertion": true,
        "disabled": false,
    }]
}

Cloud Marketing Plus

If you are a MediaMath customer, Cloud Marketing 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.

Match rule example

For this match rule, if the incoming URL includes /content/sales/ in its path, then the MediaMath JavaScript tags are added to the requested page.

{
    "matchRules": [{
        "name": "JS_Insertion_for_Sales",
        "type": "mmbMatchRule",
        "start": 0,
        "end": 0,
        "id": 0,
        "matchURL": null,
        "matches": [{
            "caseSensitive": false,
            "matchOperator": "contains",
            "matchType": "path",
            "matchValue": "/content/sales/",
            "negate": false
        }],
        "jsInsertion": true,
        "disabled": false
    }]
}

Edge Redirector

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.

Match rule example

For the following Edge Redirector match rule, any URL that uses the HTTP protocol, has a domain name of example.com, and includes test=null as a query string redirects to the following URL http://testredirect.akamai.com/test.html.

{
    "matchRules": [{
        "type": "erMatchRule",
        "end": 0,
        "id": 0,
        "matchURL": null,
        "matches": [{
            "caseSensitive": false,
            "matchOperator": "contains",
            "matchType": "protocol",
            "matchValue": "http",
            "negate": false
        },
        {
            "caseSensitive": false,
            "matchOperator": "contains",
            "matchType": "hostname",
            "matchValue": "example.com",
            "negate": false
        },
        {
            "caseSensitive": false,
            "matchOperator": "contains",
            "matchType": "query",
            "matchValue": "test=null",
            "negate": false
        }],
        "name": "rule 1",
        "redirectURL": "HTTP://testredirect.akamai.com/test.html",
        "disabled": false,
        "start": 0,
        "statusCode": 302,
        "useIncomingQueryString": false
    }]
}

Forward Rewrite

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.

Match rule example

For this match rule, if the incoming URL has http for the protocol or the hostname includes example1.com, the forward URL has the following path appended to it: /test_images/simpleimg.jpg.

{
    "matchRules": [{
        "type": "frMatchRule",
        "disabled": false,
        "end": 0,
        "id": 0,
        "matchURL": null,
        "forwardSettings": {
            "pathAndQS": "/test_images/simpleimg.jpg",
            "useIncomingQueryString": true },
        "matches": [{
            "caseSensitive": false,
            "matchOperator": "contains",
            "matchType": "protocol",
            "matchValue": "http",
            "negate": false
        },
        {
            "caseSensitive": false,
            "matchOperator": "contains",
            "matchType": "hostname",
            "matchValue": "example1.com",
            "negate": false
        }],
        "name": "rule 1",
        "start": 0
    }]
}

Input Validation

The Input Validation Cloudlet helps protect your business by confirming that the values submitted into a web application are well-formed and comply with your policies. In addition, this Cloudlet lets you to limit the number of valid form submissions and invalid attempts per user. Once the limit is reached, additional requests are denied (403) or are redirected (302) to a custom “penalty box.”

Match rule example

For the following Input Validation rule, a match is valid if the request uses the HTTP POST method; includes exactly five fields; and, of those five fields, one of them is called User.

{
    "matchRules": [{
        "type": "ivMatchRule",
        "disabled": false,
        "id": 0,
        "matches"[{
            "caseSensitive": false,
            "matchOperator": "equals",
            "matchType": "method",
            "negate": false,
            "objectMatchValue": {"type": "simple","value": ["POST"]}
        },
        {
            "caseSensitive": false,
            "matchOperator": "equals",
            "matchType": "numberOfFields",
            "negate": false,
            "objectMatchValue": {"type": "simple","value": ["5"]}
        },{
            "caseSensitive": false,
            "matchOperator": "required",
            "matchType": "parameter",
            "negate": false,
            "objectMatchValue": {"type": "object","name": "User","options": {"value": []}
        }
        }],
        "name": "SubscriberValidation",
        "start": 0},
        "end": 0
}

Phased Release

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. This Cloudlet can help facilitate a fast rollout of code changes to production with real users, allowing you to move some visitors to a new experience or deployment while retaining the flexibility to roll back immediately should you encounter challenges.

Match rule example

For this Phased Release example, 30% of the incoming requests from the 23.235.39.74 IP address are forwarded to the mynetstorage Cloudlet origin.

{
    "matchRules": [{
        "matches": [{
            "matchType": "clientip",
            "matchValue": "23.235.39.74",
            "checkIPs": "CONNECTING_IP",
            "matchOperator": "equals",
            "negate": false,
            "caseSensitive": false}],
        "start": 0,
        "end": 0,
        "disabled": false,
        "type": "cdMatchRule",
        "forwardSettings": {
            "percent": 30,
            "originId": "mynetstorage"},
        "name": "IP_39.74_rule",
        "id": null
    }]
}

Request Control

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.

Match rule example

For the following Request Control match rule, a request from the 72.246.0.0/16 or 192.0.2.0 address or from the United States are allowed through to the site.

{
    "matchRules": [{
        "type": "igMatchRule",
        "end": 0,
        "id": 0,
        "matches": [{
            "caseSensitive": false,
            "matchOperator": "contains",
            "matchType": "clientip",
            "matchValue": "72.246.0.0/16 192.0.2.0",
            "checkIPs": "CONNECTING_IP XFF_HEADERS",
            "negate": false
        },
        {
            "caseSensitive": false,
            "matchOperator": "contains",
            "matchType": "countrycode",
            "matchValue": "US",
            "checkIPs": "CONNECTING_IP",
            "negate": false
        }],
        "name": "rule 1",
        "disabled": false,
        "allowDeny":"denybranded",
        "start": 0
       }]
}

Visitor Prioritization

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

Match rule example

For the following Visitor Prioritization match rule, any URL that uses the HTTP protocol, has a domain name of source.com, and includes test=null as a query string, bypasses the waiting room and is sent directly to the origin.

{
    "matchRules": [{
        "type": "vpMatchRule",
        "end": 0,
        "id": 0,
        "matchURL": null,
        "matches": [{
            "caseSensitive": false,
            "matchOperator": "contains",
            "matchType": "protocol",
            "matchValue": "http",
            "negate": false
        },
        {
            "caseSensitive": false,
            "matchOperator": "contains",
            "matchType": "query",
            "matchValue": "test=null",
            "negate": false
        }],
        "name": "rule 1",
        "disabled": false,
        "start": 0,
        "passThroughPercent":11,
        "useIncomingQueryString": false
    }]
}

Errors

If you encounter a variety of errors, the Cloudlets API responds with appropriate HTTP status codes and a response object that explains them, detailed below. There are many possible causes for failure, such as malformed JSON or missing fields.

Error responses

The Cloudlets API responds with HTTP problem error objects that provide details useful for debugging.

The following is an example of a response with a validation error:

{
     "detail": "Exceeds maximum rules (5000). Received rule count:5001",
     "errorCode": -1,
     "errorMessage": "Exceeds maximum rules (5000). Received rule count:5001",
     "instance": "2d8290b4-30df-4025-88a8-3f596a52aef7",
     "status": 400,
     "title": "Too Many Rules",
     "type": "/cloudlets/error-types/policy-rule-count-exceeded",
     "maxRules": 5000,
     "ruleCount": 5001
}

In the response above, the error is caused by the fact that the number of rules allowed per policy has been exceeded. To resolve this issue, divide your rules up between different policies to avoid the rule maximum.

The errorCode and errorMessage members are currently included to maintain backwards compatibility with earlier error messaging formats. These members will be removed sometime during the third quarter of 2017, and will eventually disappear.

HTTP codes

The following are common HTTP codes that are used by this API:

Last modified: 1/9/2017