loading

Cloudlets API v2

Create and manage policies and policy versions for Cloudlet applications on the edge.

Learn more:


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.

Getting 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 Luna Control Center username is associated with. If your username is not associated with the group ID (gid or groupId) you selected, then the request fails.

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

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

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

Cloudlets API workflow

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

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

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

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

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

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

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

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

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

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

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

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

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

Cloudlets API workflow for cloudlets origins

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Interactions with Property Manager

Policy activation

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

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

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

Cloudlets origins

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

Activation (going live)

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

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

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

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

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

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

  • failed: The policy version activation workflow has failed.

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

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

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

Activating policy versions

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

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

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

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

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

Activation times

The following are the average activation times for each Cloudlet:

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

NetStorage activation considerations

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

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

Testing the activated policy

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

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

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

Operation Method Endpoint
Cloudlets
List Cloudlets GET /cloudlets/api/v2/cloudlet-info{?gid}
Get a Cloudlet GET /cloudlets/api/v2/cloudlet-info/{cloudletId}
Group-Level Cloudlets
List Groups GET /cloudlets/api/v2/group-info
Get a Group GET /cloudlets/api/v2/group-info/{groupId}
Policies
List Policies GET /cloudlets/api/v2/policies{?gid,includeDeleted,cloudletId,clonePolicyId,version,offset,pageSize}
Create a Policy POST /cloudlets/api/v2/policies{?gid,includeDeleted,cloudletId,clonePolicyId,version}
Get a Policy GET /cloudlets/api/v2/policies/{policyId}
Update a Policy PUT /cloudlets/api/v2/policies/{policyId}
Remove a Policy DELETE /cloudlets/api/v2/policies/{policyId}
Policy Versions
List Policy Versions GET /cloudlets/api/v2/policies/{policyId}/versions{?includeRules,matchRuleFormat,cloneVersion,offset,pageSize}
Create a New Policy Version POST /cloudlets/api/v2/policies/{policyId}/versions{?includeRules,matchRuleFormat,cloneVersion}
Get a Policy Version GET /cloudlets/api/v2/policies/{policyId}/versions/{version}{?omitRules,matchRuleFormat}
Update a Policy Version PUT /cloudlets/api/v2/policies/{policyId}/versions/{version}{?omitRules,matchRuleFormat}
Remove a Policy Version DELETE /cloudlets/api/v2/policies/{policyId}/versions/{version}{?omitRules,matchRuleFormat}
Add a Version Rule POST /cloudlets/api/v2/policies/{policyId}/versions/{version}/rules{?index}
Get a Version Rule GET /cloudlets/api/v2/policies/{policyId}/versions/{version}/rules/{akaRuleId}
Update a Version Rule PUT /cloudlets/api/v2/policies/{policyId}/versions/{version}/rules/{akaRuleId}
Property Associations
List Associated Properties GET /cloudlets/api/v2/properties
Get Associated Properties for a Policy GET /cloudlets/api/v2/policies/{policyId}/properties
Load Balancing Configurations for Application Load Balancer
List Cloudlets Origins GET /cloudlets/api/v2/origins{?type}
Get a Cloudlets Origin GET /cloudlets/api/v2/origins/{originId}
Create a Load Balancing Configuration POST /cloudlets/api/v2/origins/{originId}
Update a Load Balancing Configuration PUT /cloudlets/api/v2/origins/{originId}
List Load Balancing Versions GET /cloudlets/api/v2/origins/{originId}/versions
Create a Load Balancing Version POST /cloudlets/api/v2/origins/{originId}/versions
Get a Load Balancing Version GET /cloudlets/api/v2/origins/{originId}/versions/{version}{?validate}
Update a Load Balancing Version PUT /cloudlets/api/v2/origins/{originId}/versions/{version}{?validate}
Load Balancing Version Activations
List Current Load Balancing Activations GET /cloudlets/api/v2/origins/currentActivations
List Activations for a Load Balancing Configuration GET /cloudlets/api/v2/origins/{originId}/activations
Activate a Load Balancing Version POST /cloudlets/api/v2/origins/{originId}/activations
Policy Activations
List Policy Activations GET /cloudlets/api/v2/policies/{policyId}/activations{?network,propertyName}
Activate a Policy Version POST /cloudlets/api/v2/policies/{policyId}/versions/{version}/activations
Schemas
Get a Schema GET /cloudlets/api/v2/schemas/{schemaName}
List Schemas per Cloudlet GET /cloudlets/api/v2/schemas{?cloudletType}

List cloudlets

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

GET /cloudlets/api/v2/cloudlet-info{?gid}

Sample: /cloudlets/api/v2/cloudlet-info?gid=11754

Parameter Type Sample Description
Required
gid Number 11754 For GET operations, returns data about the available types of Cloudlets the user can access for the specified group ID.

Status 200 application/json

Response Body:

[
    {
        "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.

GET /cloudlets/api/v2/cloudlet-info/{cloudletId}

Sample: /cloudlets/api/v2/cloudlet-info/1001

Parameter Type Sample Description
Optional
cloudletId Number 1001 For GET operations, returns only policies for this particular cloudletId.

Status 200 application/json

Response Body:

{
    "serviceVersion": null,
    "apiVersion": "2.0",
    "location": "/cloudlets/api/v2/cloudlet-info/0",
    "cloudletId": 0,
    "cloudletCode": "ER",
    "cloudletName": "EDGEREDIRECTOR"
}
  1. Run the List Cloudlets operation.

  2. Store the cloudletId from the appropriate object within the listing.

  3. Make a GET request to /cloudlets/api/v2/cloudlet-info{?gid}.

List groups

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

GET /cloudlets/api/v2/group-info

Status 200 application/json

Response Body:

[
    {
        "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.

GET /cloudlets/api/v2/group-info/{groupId}

Sample: /cloudlets/api/v2/group-info/11754

Parameter Type Sample Description
Required
groupId Number 11754 For GET operations, returns only policies associated with the group ID entered. Enter 0 to get policies in all groups.

Status 200 application/json

Response Body:

[
    {
        "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
    }
]
  1. Run the List Groups operation.

  2. Store the groupId from the appropriate object within the listing.

  3. Make a GET request to /cloudlets/api/v2/group-info/{groupId}.

List policies

Returns information for all available policies.

GET /cloudlets/api/v2/policies{?gid,includeDeleted,cloudletId,clonePolicyId,version,offset,pageSize}

Sample: /cloudlets/api/v2/policies?gid=11754&includeDeleted=false&cloudletId=1001&clonePolicyId=11754&version=10

Parameter Type Sample Description
Optional
clonePolicyId Number 11754 If cloning an existing policy, this parameter is the ID of the policy (policyId) you want to clone. If there are attributes that you do not want propagated from the source policy, you must provide the new values in the request.
cloudletId Number 1001 For GET operations, returns only policies for this particular cloudletId.
gid Number 11754 For GET operations, returns only policies associated with the group ID (gid) entered.
includeDeleted Boolean false For GET operations, includes deleted policies in the results.
version Number 10 For POST operations, indicates the version of the existing policy to use for the new policy. If not specified, the latest version of the existing policy is copied.
offset Number 25 When requesting pages of data, offset is the record after which to start. Use with pageSize to page through data. Ex: offset=25&pageSize=25 will start at record 26 and display 25 records.
pageSize Number 10 The number of records to return. Use with offset to page through data.

Status 200 application/json

Response Body:

[
    {
        "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.

POST /cloudlets/api/v2/policies{?gid,includeDeleted,cloudletId,clonePolicyId,version}

Sample: /cloudlets/api/v2/policies?gid=11754&includeDeleted=false&cloudletId=1001&clonePolicyId=11754&version=10

Content-Type: application/json

Request Body:

{
    "cloudletId": 99,
    "groupId": 1234,
    "name": "TestCreatePolicy1",
    "description": "Testing the creation of a policy"
}
Parameter Type Sample Description
Optional
clonePolicyId Number 11754 If cloning an existing policy, this parameter is the ID of the policy (policyId) you want to clone. If there are attributes that you do not want propagated from the source policy, you must provide the new values in the request.
cloudletId Number 1001 For GET operations, returns only policies for this particular cloudletId.
gid Number 11754 For GET operations, returns only policies associated with the group ID (gid) entered.
includeDeleted Boolean false For GET operations, includes deleted policies in the results.
version Number 10 For POST operations, indicates the version of the existing policy to use for the new policy. If not specified, the latest version of the existing policy is copied.

Status 200 application/json

Response Body:

{
    "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": []
}
  1. Run the List Cloudlets operation and store the cloudletId.

  2. Run the List Groups operation and store the groupId.

  3. Create a JSON file with the following required members: cloudletId, groupId, name. See the Policy for a listing of all members.

  4. Make a POST request to /cloudlets/api/v2/policies, specifying the JSON in the body of the request.

Get a policy

Returns information about a specific Cloudlets policy.

GET /cloudlets/api/v2/policies/{policyId}

Sample: /cloudlets/api/v2/policies/11754

Parameter Type Sample Description
Required
policyId Number 11754 The ID of the policy.

Status 200 application/json

Response Body:

{
    "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
            }
        }
    ]
}
  1. Run the List Policies operation.

  2. Store the policyId from the appropriate object within the listing.

  3. Make a GET request to /cloudlets/api/v2/policies/{policyId}.

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.

PUT /cloudlets/api/v2/policies/{policyId}

Sample: /cloudlets/api/v2/policies/11754

Content-Type: application/json

Request Body:

{
    "description": "Testing the update of a policy",
}
Parameter Type Sample Description
Required
policyId Number 11754 The ID of the policy.

Status 200 application/json

Response Body:

{
    "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": []
}
  1. Run the List Policies operation.

  2. Store the policyId from the appropriate object within the listing.

  3. Run the Get a Policy operation for the selected policyId.

  4. Modify the JSON file returned with the desired updates to the policy.

  5. Make a PUT request to /cloudlets/api/v2/policies/{policyId}, specifying the modified JSON in the body of the request.

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).

DELETE /cloudlets/api/v2/policies/{policyId}

Sample: /cloudlets/api/v2/policies/11754

Parameter Type Sample Description
Required
policyId Number 11754 The ID of the policy.

Status 204

  1. Run the List Policies operation.

  2. Store the policyId from the appropriate object within the listing.

  3. Make a DELETE request to /cloudlets/api/v2/policies/{policyId}.

List policy versions

Returns information about all versions of a policy.

GET /cloudlets/api/v2/policies/{policyId}/versions{?includeRules,matchRuleFormat,cloneVersion,offset,pageSize}

Sample: /cloudlets/api/v2/policies/11754/versions?includeRules=false&matchRuleFormat=1.0&cloneVersion=10

Parameter Type Sample Description
Required
policyId Number 11754 The ID of the policy.
Optional
cloneVersion Number 10 If cloning an existing policy version, this parameter value is the number of the policy version you want to clone. If there are attributes that you do not want propagated from the source policy version, you must provide the new values in the request.
includeRules Boolean false Includes the match rules for all policy versions in the results. Defaults to false.
matchRuleFormat String 1.0 Returns the matchRuleFormat version string, which shows the version of the Cloudlet-specific matchRules used. Defaults to 1.0.
offset Number 25 When requesting pages of data, offset is the record after which to start. Use with pageSize to page through data. Ex: offset=25&pageSize=25 will start at record 26 and display 25 records.
pageSize Number 10 The number of records to return. Use with offset to page through data.

Status 200 application/json

Response Body:

[
    {
        "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
    }
]
  1. Run the List Policies operation.

  2. Store the policyId from the appropriate object within the listing.

  3. Make a GET request to /cloudlets/api/v2/policies/{policyId}/versions to return all versions of the policy.

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.

POST /cloudlets/api/v2/policies/{policyId}/versions{?includeRules,matchRuleFormat,cloneVersion}

Sample: /cloudlets/api/v2/policies/11754/versions?includeRules=false&matchRuleFormat=1.0&cloneVersion=10

Content-Type: application/json

Request Body:

{
    "description": "Testing the cloning of a policy",
    "matchRuleFormat": "1.0",
    "matchRules": []
}
Parameter Type Sample Description
Required
policyId Number 11754 The ID of the policy.
Optional
cloneVersion Number 10 If cloning an existing policy version, this parameter value is the number of the policy version you want to clone. If there are attributes that you do not want propagated from the source policy version, you must provide the new values in the request.
includeRules Boolean false Includes the match rules for all policy versions in the results. Defaults to false.
matchRuleFormat String 1.0 Returns the matchRuleFormat version string, which shows the version of the Cloudlet-specific matchRules used. Defaults to 1.0.

Status 200 application/json

Response Body:

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

  2. Store the policyId from the appropriate object within the listing.

  3. Make a POST request to /cloudlets/api/v2/policies/{policyId}/versions.

Get a policy version

Returns information about a specific Cloudlet policy version.

GET /cloudlets/api/v2/policies/{policyId}/versions/{version}{?omitRules,matchRuleFormat}

Sample: /cloudlets/api/v2/policies/11754/versions/10?omitRules=false&matchRuleFormat=1.0

Parameter Type Sample Description
Required
policyId Number 11754 The ID of the policy.
version Number 10 The version number of the policy.
Optional
matchRuleFormat String 1.0 Returns the matchRuleFormat version string, which shows the version of the Cloudlet-specific matchRules used. Defaults to 1.0.
omitRules Boolean false Excludes the match rules from the results. Defaults to false.

Status 200 application/json

Response Body:

{
    "revisionId": 11870,
    "policyId": 1001,
    "version": 2,
    "description": "v2",
    "createdBy": "jsmith",
    "createDate": 1427133784903,
    "lastModifiedBy": "sjones",
    "lastModifiedDate": 1427133805767,
    "activations": [],
    "matchRules": [],
    "rulesLocked": false
}
  1. Run the List Policies operation.

  2. Store the policyId from the appropriate object within the listing.

  3. Run the List Policy Versions operation.

  4. Store the version from the appropriate object within the listing.

  5. Make a GET request to /cloudlets/api/v2/policies/{policyId}/versions/{version}.

Update a policy version

Update attributes of an existing policy version.

PUT /cloudlets/api/v2/policies/{policyId}/versions/{version}{?omitRules,matchRuleFormat}

Sample: /cloudlets/api/v2/policies/11754/versions/10?omitRules=false&matchRuleFormat=1.0

Content-Type: application/json

Request Body:

{ "description": "v1 for Q1 Sales" }
Parameter Type Sample Description
Required
policyId Number 11754 The ID of the policy.
version Number 10 The version number of the policy.
Optional
matchRuleFormat String 1.0 Returns the matchRuleFormat version string, which shows the version of the Cloudlet-specific matchRules used. Defaults to 1.0.
omitRules Boolean false Excludes the match rules from the results. Defaults to false.

Status 200 application/json

Response Body:

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

  2. Store the policyId from the appropriate object within the listing.

  3. Run the List Policy Versions operation.

  4. Store the version you want to update.

  5. Run the Get a Policy Version operation.

  6. Modify the JSON file returned with any changes to match rules or version-level information. The description and matchRuleFormat members are required.

  7. Make a PUT request to /cloudlets/api/v2/policies/{policyId}/versions/{version}, specifying the modified JSON in the body of the request.

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).

DELETE /cloudlets/api/v2/policies/{policyId}/versions/{version}{?omitRules,matchRuleFormat}

Sample: /cloudlets/api/v2/policies/11754/versions/10?omitRules=false&matchRuleFormat=1.0

Parameter Type Sample Description
Required
policyId Number 11754 The ID of the policy.
version Number 10 The version number of the policy.
Optional
matchRuleFormat String 1.0 Returns the matchRuleFormat version string, which shows the version of the Cloudlet-specific matchRules used. Defaults to 1.0.
omitRules Boolean false Excludes the match rules from the results. Defaults to false.

Status 204

  1. Run the List Policies operation.

  2. Store the policyId from the appropriate object within the listing.

  3. Run the List Policy Versions operation.

  4. Store the version from the appropriate object within the listing.

  5. Make a DELETE request to /cloudlets/api/v2/policies/{policyId}/versions/{version}.

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.

POST /cloudlets/api/v2/policies/{policyId}/versions/{version}/rules{?index}

Sample: /cloudlets/api/v2/policies/11754/versions/10/rules?index=3

Content-Type: application/json

Request Body:

{
    "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
}
Parameter Type Sample Description
Required
policyId Number 11754 The ID of the policy.
version Number 10 The version number of the policy.
Optional
index Number 3 The order within the current list of rules where you want to add the new rule. 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.

Status 200 application/json

Response Body:

{
    "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
}
  1. Run the List Policies operation.

  2. Store the policyId from the appropriate object within the listing.

  3. Run the List Policy Versions operation with the includeRules query parameter set to true.

  4. Store the version number and the akaRuleId from the appropriate object within the listing.

  5. Create a JSON file with the new match rules.

  6. Make a POST request to /cloudlets/api/v2/policies/{policyId}/versions/{version}/rules, specifying the JSON in the body of the request.

Get a version rule

Returns information about a specific rule within a policy version.

GET /cloudlets/api/v2/policies/{policyId}/versions/{version}/rules/{akaRuleId}

Sample: /cloudlets/api/v2/policies/11754/versions/10/rules/5db847a66e0566ad

Parameter Type Sample Description
Required
akaRuleId String 5db847a66e0566ad The ID of the rule within the policy version.
policyId Number 11754 The ID of the policy.
version Number 10 The version number of the policy.

Status 200 application/json

Response Body:

{
    "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
}
  1. Run the List Policies operation.

  2. Store the policyId from the appropriate object within the listing.

  3. Run the List Policy Versions operation with the includeRules query parameter set to true.

  4. Store the version number and the akaRuleId from the appropriate object within the listing.

  5. Make a GET request to /cloudlets/api/v2/policies/{policyId}/versions/{version}/rules/{akaRuleId}.

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.

PUT /cloudlets/api/v2/policies/{policyId}/versions/{version}/rules/{akaRuleId}

Sample: /cloudlets/api/v2/policies/11754/versions/10/rules/5db847a66e0566ad

Content-Type: application/json

Request Body:

{ "disabled": "true" }
Parameter Type Sample Description
Required
akaRuleId String 5db847a66e0566ad The ID of the rule within the policy version.
policyId Number 11754 The ID of the policy.
version Number 10 The version number of the policy.

Status 200 application/json

Response Body:

{
    "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
}
  1. Run the List Policies operation.

  2. Store the policyId from the appropriate object within the listing.

  3. Run the List Policy Versions operation with the includeRules query parameter set to true.

  4. Store the version number and the akaRuleId from the appropriate object within the listing.

  5. Create a JSON file with any changes to match rules.

  6. Make a PUT request to /cloudlets/api/v2/policies/{policyId}/versions/{version}/rules/{akaRuleId}, specifying the JSON in the body of the request.

List associated properties

GET /cloudlets/api/v2/properties

Status 200 application/json

Response Body:

{
    "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

GET /cloudlets/api/v2/policies/{policyId}/properties

Sample: /cloudlets/api/v2/policies/11754/properties

Parameter Type Sample Description
Required
policyId Number 11754 The ID of the policy.

Status 200 application/json

Response Body:

{
    "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"
            ]
        }
    }
}
  1. Run the List Policies operation.

  2. Store the policyId from the appropriate object within the listing.

  3. Make a GET request to /cloudlets/api/v2/policies/{policyId}/properties, which returns a list of associated properties for a policy

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.

GET /cloudlets/api/v2/origins{?type}

Sample: /cloudlets/api/v2/origins?type=APPLICATION_LOAD_BALANCER

Parameter Type Sample Description
Optional
type String APPLICATION_LOAD_BALANCER Returns data for a specific type of origin as defined in Property Manager. Options include alb for Application Load Balancer origins, customer for standard origins, and netstorage for NetStorage-based origins.

Status 200 application/json

Response Body:

[
    {
        "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.

GET /cloudlets/api/v2/origins/{originId}

Sample: /cloudlets/api/v2/origins/clorigin1

Parameter Type Sample Description
Required
originId String clorigin1 Unique identifier for the origin.

Status 200 application/json

Response Body:

[
    {
        "originId": "clorigin1",
        "checksum": "abcdefg1111hijklmn22222fff76yae3",
        "description": "Origin for mobile user forwarding."
        "type": "APPLICATION_LOAD_BALANCER"
    }
]
  1. Run the List Cloudlets Origins operation.

  2. Store the originId from the appropriate object within the listing.

  3. Make a GET request to /cloudlets/api/v2/origins/{originId}.

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.

POST /cloudlets/api/v2/origins/{originId}

Sample: /cloudlets/api/v2/origins/clorigin1

Parameter Type Sample Description
Required
originId String clorigin1 Unique identifier for the origin.

Status 200 application/json

Response Body:

{
    "originId": "clorigin1",
    "checksum": "abcdefg1111hijklmn22222fff76yae3",
    "description": "Test load balancing configuration."
    "type": "APPLICATION_LOAD_BALANCER"
}
  1. Run the List Cloudlets Origins operation to verify that the originId you want to create isn’t already in use.

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

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.

PUT /cloudlets/api/v2/origins/{originId}

Sample: /cloudlets/api/v2/origins/clorigin1

Content-Type: application/json

Request Body:

{
    "description": "Test load balancing configuration."
}
Parameter Type Sample Description
Required
originId String clorigin1 Unique identifier for the origin.

Status 200 application/json

Response Body:

{
    "originId": "clorigin1",
    "checksum": "abcdefg1111hijklmn22222fff76yae3",
    "description": "Test load balancing configuration."
    "type": "APPLICATION_LOAD_BALANCER"
}
  1. Run the List Cloudlets Origins operation.

  2. Store the originId from the appropriate object within the listing.

  3. Create a JSON file with an updated entry for the description member.

  4. Make a PUT request to /cloudlets/api/v2/origins/{originId}, specifying the JSON in the body of the request.

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.

GET /cloudlets/api/v2/origins/{originId}/versions

Sample: /cloudlets/api/v2/origins/clorigin1/versions

Parameter Type Sample Description
Required
originId String clorigin1 Unique identifier for the load balancing configuration.

Status 200 application/json

Response Body:

[
    {
        "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
    }
]
  1. Run the List Cloudlets Origins operation.

  2. Store the originId from the appropriate object within the listing.

  3. Make a GET request to /cloudlets/api/v2/origins/{originId}/versions.

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.

POST /cloudlets/api/v2/origins/{originId}/versions

Sample: /cloudlets/api/v2/origins/clorigin1/versions

Content-Type: application/json

Request Body:

{
    "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
}
Parameter Type Sample Description
Required
originId String clorigin1 Unique identifier for the load balancing configuration.

Status 201 application/json

Response Body:

{
    "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
}
  1. Run the List Cloudlets Origins operation.

  2. Store the originId from the appropriate object within the listing.

  3. Create a JSON file with the following required members: cloudletId, originId, name. See the Cloudlets Origin members for a listing of all members.

  4. Make a POST request to /cloudlets/api/v2/origins/{originId}/versions, specifying the JSON in the body of the request.

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.

GET /cloudlets/api/v2/origins/{originId}/versions/{version}{?validate}

Sample: /cloudlets/api/v2/origins/clorigin1/versions/1?validate=false

Parameter Type Sample Description
Required
originId String clorigin1 Unique identifier for the load balancing configuration.
version Number 1 The origin version.
Optional
validate Boolean false For GET operations, verifies that the current settings for the selected originId and version are valid.

Status 200 application/json

Response Body:

{
    "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
}
  1. Run the List Cloudlets Origins operation.

  2. Store the originId from the appropriate object within the listing. The object should also have an originType of APPLICATION_LOAD_BALANCER.

  3. Run the List Cloudlets Origin Versions operation.

  4. Store the version from the appropriate object within the listing.

  5. Make a GET request to /cloudlets/api/v2/origins/{originId}/versions/{version}.

Update a load balancing version

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

PUT /cloudlets/api/v2/origins/{originId}/versions/{version}{?validate}

Sample: /cloudlets/api/v2/origins/clorigin1/versions/1?validate=false

Content-Type: application/json

Request Body:

{
    "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
}
Parameter Type Sample Description
Required
originId String clorigin1 Unique identifier for the load balancing configuration.
version Number 1 The origin version.
Optional
validate Boolean false For GET operations, verifies that the current settings for the selected originId and version are valid.

Status 200 application/json

Response Body:

{
    "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
}
  1. Run the List Cloudlets Origins operation.

  2. Store the originId from the appropriate object within the listing. The object should also have an originType of APPLICATION_LOAD_BALANCER.

  3. Run the List Cloudlets Origin Versions operation.

  4. Store the version from the appropriate object within the listing.

  5. Run the Get a Cloudlets Origin Version operation.

  6. Create a JSON file with any changes to the Cloudlets Origin members.

  7. Make a PUT request to /cloudlets/api/v2/origins/{originId}/versions/{version}, specifying the JSON in the body of the request.

List current load balancing activations

GET /cloudlets/api/v2/origins/currentActivations

Status 200 application/json

Response Body:

{
    "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.

GET /cloudlets/api/v2/origins/{originId}/activations

Sample: /cloudlets/api/v2/origins/clorigin1/activations

Parameter Type Sample Description
Required
originId String clorigin1 Unique identifier for the load balancing configuration.

Status 200 application/json

Response Body:

[
    {
        "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
    }
]
  1. Run the List Cloudlets Origins operation.

  2. Store the originId from the appropriate object within the listing. The object should also have an originType of APPLICATION_LOAD_BALANCER.

  3. Make a GET request to /cloudlets/api/v2/origins/{originId}/activations.

Activate a load balancing version

POST /cloudlets/api/v2/origins/{originId}/activations

Sample: /cloudlets/api/v2/origins/clorigin1/activations

Content-Type: application/json

Request Body:

{
    "network": "STAGING",
    "dryrun": false,
    "version": 1
}
Parameter Type Sample Description
Required
originId String clorigin1 Unique identifier for the load balancing configuration.

Status 200 application/json

Response Body:

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

  2. Store the originId from the appropriate object within the listing. The object should also have an originType of APPLICATION_LOAD_BALANCER.

  3. Create a JSON file that includes the required version and network members as listed in the Load Balancing Version Activations for Application Load Balancer section of the data model.

  4. Make a POST request to /cloudlets/api/v2/origins/{originId}/activations, specifying the JSON in the body of the request.

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.

GET /cloudlets/api/v2/policies/{policyId}/activations{?network,propertyName}

Sample: /cloudlets/api/v2/policies/11754/activations?network=prod&propertyName=prod

Parameter Type Sample Description
Required
policyId Number 11754 The ID of the policy.
Optional
network String prod Returns only activations for the selected network, either staging or prod.
propertyName String prod Returns only activations for the selected property.

Status 200 application/json

Response Body:

[
    {
    "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
        }
    }
]
  1. Run the List Policies operation.

  2. Store the policyId from the appropriate object within the listing.

  3. Make a GET request to /cloudlets/api/v2/policies/{policyId}/activations, which returns a list of activations for a specific policy.

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.

POST /cloudlets/api/v2/policies/{policyId}/versions/{version}/activations

Sample: /cloudlets/api/v2/policies/11754/versions/10/activations

Parameter Type Sample Description
Required
policyId Number 11754 The ID of the policy.
version Number 10 The version number of the policy.
  1. If not done already, use the Property Manager API (PAPI) to set up the behavior for each Cloudlet you are configuring:

  2. Run the List Policies operation.

  3. Store the policyId from the appropriate object within the listing.

  4. Run the List Policy Versions operation.

  5. Store the version from the appropriate object within the listing.

  6. Run the Get Associated Properties for a Policy operation.

  7. Store the name of any property that you want to associate with the policy version being activated.

  8. Create a JSON file with information about the network to activate on (staging or production), as well as any optional properties to associate with Cloudlets policy version.

  9. Make a POST request to /cloudlets/api/v2/policies/{policyId}/versions/{version}/activations, specifying the JSON in the body of the request.

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.

Action to Validate JSON Schema Name
Create a new policy create-policy.json
Update a policy update-policy.json
Clone an existing policy clone-policy.json
Create or clone a policy version create-nimbus_policy_version-{cloudletType}-1.0.json
Update a policy version update-nimbus_policy_version-{cloudletType}-1.0.json
Create or update a match rule match_rule-{cloudletType}-1.0.json

GET /cloudlets/api/v2/schemas/{schemaName}

Sample: /cloudlets/api/v2/schemas/create-policy.json

Parameter Type Sample Description
Required
schemaName String create-policy.json The name of the JSON schema file.

Status 200 application/json

Response Body:

{
    "$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.

GET /cloudlets/api/v2/schemas{?cloudletType}

Sample: /cloudlets/api/v2/schemas?cloudletType=ER

Parameter Type Sample Description
Optional
cloudletType String ER The two- or three- letter code of the Cloudlet you want to view all schemas for. This value corresponds to the cloudletCode member available from List Cloudlets.

Status 200 application/json

Response Body:

{
    "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

Member Type Description
Required
apiVersion String The specific version of this API.
cloudletCode Enumeration The two- or three- character code for the type of Cloudlet. Possible values include: ALB for Application Load Balancer, AP for API Prioritization, AS for Audience Segmentation, CD for Phased Release, ER for Edge Redirector, FR for Forward Rewrite, IG for Request Control, IV for Input Validation, and VP for Visitor Prioritization.
cloudletId Number An integer that corresponds to a Cloudlets policy type.
cloudletName Enumeration The full name of the Cloudlet. The available options for this field are APPLICATIONLOADBALANCER, ASSETPRIORITIZATION for API Prioritization, AUDIENCESEGMENTATION, CONTINUOUSDEPLOYMENT for Phased Release, EDGEREDIRECTOR, FORWARDREWRITE, INPUTVALIDATION, IPGEOACCESS for Request Control, , and VISITORPRIORITIZATION.
location String The navigable endpoint used for the object referred to in the operation.
Deprecated
serviceVersion String The build of the software running on the server.

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

Member Type Description
Required
apiVersion String The specific version of this API.
capabilities GroupInfo.capabilities[] An array of type and permission information for each Cloudlet, as detailed below.
groupId Number The group association for the policy. If 0, the policy is not tied to a group and in effect appears in all groups for the account.
groupName String The name of the group.
location String The navigable endpoint used for the object referred to in the operation.
parentId Number The ID of the parent group. If you do not have edit permission for the parent group, this value is 0 and the parent group does not appear in the response.
properties Array An array of the properties associated with the selected group.
Deprecated
serviceVersion String The build of the software running on the server.

GroupInfo.capabilities[]  

Member Type Description
Required
capabilities Enumeration The permissions available for that Cloudlet. Possible values include: Activate, Edit, and View.
cloudletCode Enumeration The two- or three- character code for the type of Cloudlet. Possible values include: ALB for Application Load Balancer, AP for API Prioritization, AS for Audience Segmentation, CD for Phased Release, ER for Edge Redirector, FR for Forward Rewrite, IG for Request Control, IV for Input Validation, and VP for Visitor Prioritization.
cloudletId Number An integer that corresponds to a Cloudlets policy type.

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

Member Type Description
Optional
activations Policy.activations[] An array of current policy activation information, as detailed below.
apiVersion String The specific version of this API.
cloudletCode Enumeration The two- or three- character code for the type of Cloudlet. Possible values include: ALB for Application Load Balancer, AP for API Prioritization, AS for Audience Segmentation, CD for Phased Release, ER for Edge Redirector, FR for Forward Rewrite, IG for Request Control, IV for Input Validation, and VP for Visitor Prioritization.
cloudletId Number Required in POST request, unless you are cloning a policy. Defines the policy type. If you include this property in a clone request, the value must match the policy type of the policy being cloned. Use the Cloudlet Information operations to retrieve this value.
createdBy String The name of the user who created this specific policy.
createDate Number The date this specific policy was created (in milliseconds since Epoch).
deleted Boolean If true, the policy has been deleted.
description String The description of this specific policy.
groupId Number Required in POST request, unless you are cloning a policy. Defines the group association for the policy. You must have edit privileges for the group. If 0, the policy is not tied to a group and in effect appears in all groups for the account. Use -1 to request policies from your default group.
lastModifiedBy String The user who last modified the policy.
lastModifiedDate Number The date the initial policy was modified (in milliseconds since Epoch).
location String The navigable endpoint used for the object referred to in the operation.
matchRuleFormat String The version of the Cloudlet-specific matchRules.
matchRules Array A JSON structure that defines the rules for this policy. See Cloudlets API Match Rules for details.
name String Required in POST request. The name of the policy. The name must be unique.
policyId Number An integer ID that is associated with all versions of a policy.
rulesLocked Boolean If true, you cannot edit the match rules for the Cloudlet policy version.
Deprecated
propertyName String This property now only returns null. It does not reflect the properties currently associated with this Cloudlets policy.
serviceVersion String The build of the software running on the server.

Policy.activations[]  

Member Type Description
Required
network Enumeration The network, either staging or prod on which a property or a Cloudlets policy has been activated.
policyInfo Activation.policyInfo The object containing Cloudlet policy information, as detailed below.
propertyInfo Activation.propertyInfo The object containing information about the property associated with a particular Cloudlet policy, as detailed below.
Optional
apiVersion String The specific version of this API.
Deprecated
serviceVersion String The build of the software running on the server.

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

Member Type Description
Optional
activations PolicyVersion.activations[] An array of activation information, as detailed below.
akaRuleId String The rule’s unique identifier.
createdBy String The name of the user who created this specific policy.
createDate Number The date this specific policy was created (in milliseconds since Epoch).
description String Required for POST request. The description of this specific policy.
lastModifiedBy String The user who last modified the policy.
lastModifiedDate Number The date the initial policy was modified (in milliseconds since Epoch).
matchRuleFormat String Required for POST request. The version of the Cloudlet-specific matchRules.
matchRules Array A JSON structure that defines the rules for this policy. See Cloudlets API Match Rules for details.
policyId Number An integer ID that is associated with all versions of a policy.
revisionId Number Unique ID given to every policy version update.
rulesLocked Boolean If true, you cannot edit the match rules for the Cloudlet policy version.
version String The version number of an activated policy (policyInfo) or property (propertyInfo).

PolicyVersion.activations[]  

Member Type Description
Optional
apiVersion String The specific version of this API.
network Enumeration The network, either staging or prod on which a property or a Cloudlets policy has been activated.
policyInfo Activation.policyInfo The object containing Cloudlet policy information, as detailed below.
propertyInfo Activation.propertyInfo The object containing information about the property associated with a particular Cloudlet policy, as detailed below.
Deprecated
serviceVersion String The build of the software running on the server.

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.*

Members Type Description
Required
groupId Number The group association for the property.
name String The name of the property. This value also appears at the start of each separate property object.
newestVersion PropertyAssociation.*.* An object that contains information about the newest property version.
production PropertyAssociation.*.* An object that contains information about the property’s current configuration on the production network.
staging PropertyAssociation.*.* An object that contains information about the property’s current configuration on the staging network.

PropertyAssociation.*.*

Members Type Description
Optional
activatedBy String The name of the user who activated property.
activationDate Number The date on which the property was activated (in ISO 8601 format).
cloudletsOrigins PropertyAssociation.*.*.cloudletsOrigins.* An object that contains information about each Cloudlets Origin configured on the property, as described below.
referencedPolicies Array The names of Cloudlets policies associated with this version of the property. All values in this array are strings. To retrieve policy information, construct a URL with one of the values listed and the id from the PropertyAssociation.*.*.cloudletsOrigins.* object.
version String The version number of the property.

PropertyAssociation.*.*.cloudletsOrigins.*

Members Type Description
Optional
checksum String The checksum that distinguishes this Cloudlets Origin from any others that might share the same name.
hostname String The name of the host that can be used as a Cloudlets Origin.
id String The Cloudlets Origin’s unique identifier.
type Enumeration The type of origin this Cloudlets Origin is set up as. Options are either CUSTOMER or NETSTORAGE.

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

Members Type Description
Optional
checksum String The checksum that distinguishes this Cloudlets Origin from any others that might share the same name.
hostname String The name of the host that can be used as a Cloudlets Origin.
originId String The Cloudlets Origin’s unique identifier.
type Enumeration The type of origin this Cloudlets Origin is set up as. Options are APPLICATION_LOAD_BALANCER, CUSTOMER, and NETSTORAGE.

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

Member Type Description
Required
balancingType Enumeration The type of load balancing being performed. Options include WEIGHTED and PERFORMANCE.
dataCenters LoadBalancingVersion.dataCenters[] The object containing information on Cloudlets Origins being used as data centers for an Application Load Balancer implementation, as detailed below. Only Cloudlets Origins with an originType of CUSTOMER or NETSTORAGE can be used as data centers in an Application Load Balancer configuration.
deleted Boolean If true, the Cloudlets Origin version has been deleted. If you set this member to false, you can use this version again.
description String The description of the load balancing configuration provided by a user.
Optional
createdBy String The name of the user who created this load balancing configuration.
createdDate String The date, in ISO 8601 format, when this load balancing configuration was created.
lastModifiedBy String The user who last modified the load balancing configuration.
lastModifiedDate String The date, in ISO 8601 format, when the initial load balancing configuration was last modified.
livenessSettings CloudletsOrigin.livenessSettings The object containing information on the liveness settings for an Application Load Balancer implementation, as detailed below.
originId String Unique identifier for the Cloudlets Origin that supports the load balancing configuration. The Cloudlets Origin must have an originType of APPLICATION_LOAD_BALANCER. The originType is defined in the Origin behavior.
version Number The version number of the load balancing configuration.

LoadBalancingVersion.dataCenters[]  

Member Type Description
Required
continent String The continent on which the data center is located. See Continent Codes for a list of valid codes.
country String The country in which the data center is located. See Country Codes for a list of valid codes.
latitude Number The latitude value for the data center. This member supports six decimal places of precision.
longitude Number The longitude value for the data center. This member supports six decimal places of precision.
originId String The ID of an origin that represents the data center. The Cloudlets Origin, which is defined in the Property Manager API, must have an originType of either CUSTOMER or NET_STORAGE. The originType is defined in the Origin behavior.
percent Number The percent of traffic that is sent to the data center. The total for all CloudletsOrigin.dataCenters[] objects within the array must equal 100%.
Optional
city String The city in which the data center is located.
cloudService Boolean If true caching for the data center is updated at a certain interval, like it would for a cloud-based service.
livenessHosts Array An array of strings that represent the origin servers used to poll the data centers in an Application Load Balancer configuration. These servers support basic HTTP polling.
stateOrProvince String The state, province, or region where the data center is located.

LoadBalancingVersion.livenessSettings

Member Type Description
Required
path String The path to the test object used for liveness testing. The function of the test object is to help determine whether the data center is functioning.
port Number The port for the test object. The default port is 80, which is standard for HTTP. Enter 443 if you are using HTTPS.
protocol Enumeration The protocol or scheme for the database, either HTTP or HTTPS.
status3xxFailure Boolean Set to true to mark the liveness test as failed when the request returns a 3xx (redirection) status code.
status4xxFailure Boolean Set to true to mark the liveness test as failed when the request returns a 4xx (client error) status code.
status5xxFailure Boolean Set to true to mark the liveness test as failed when the request returns a 5xx (server error) status code.
Optional
hostHeader String The value of the Host header of the domain that you are adding Application Load Balancer to. The Host header is the domain name without the scheme. For example, the hostheader for https://www.example.com would be www.example.com.
immutable Boolean Denotes whether you can edit the load balancing version. The default setting for this member is false. It automatically becomes true when the load balancing version is activated for the first time.
interval Number How often the liveness test occurs in seconds. Optional defaults to 60 seconds, minimum is 10 seconds.
timeout Number The number of seconds the system waits before failing the liveness test. The default is 25 seconds.

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

Member Type Description
Required
network Enumeration Required in POST request. The network, either STAGING or PRODUCTION, on which a load balancing configuration for Application Load Balancer has been activated.
originId String Unique identifier for the load balancing configuration.
version String The version number of the activated load balancing configuration.
Optional
activatedBy String The name of the user who activated the load balancing configuration.
activatedDate String The date, in ISO 8601 format, on which the load balancing configuration was activated.
dryrun Boolean If true, the operation validates the configuration, but does not activate the load balancing version. The default setting is false.
status Enumeration The activation status for the load balancing version. Values include the following: inactive where the load balancing version has not been activated. No active property versions reference this policy. active where the load balancing version is currently active (published) and its associated property version is also active. deactivated where the load balancing version was previously activated but it has been superseded by a more recent activation of another load balancing version. pending where the load balancing version is proceeding through the activation workflow. failed where the activation workflow for the load balancing version has failed.

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

Member Type Description
Optional
additionalPropertyNames Array An array of one or more additional properties that you want to activate with the Cloudlet policy. Once activated, the property and policy are permanently associated with each other.
apiVersion String The specific version of this API.
network Enumeration Required in POST request. The network, either staging or prod, on which a property or a Cloudlets policy has been activated.
policyInfo Activation.policyInfo The object containing Cloudlet policy information, as detailed below.
propertyInfo Activation.propertyInfo The object containing information about the property associated with a particular Cloudlet policy, as detailed below.
Deprecated
serviceVersion String The build of the software running on the server.

Activation.policyInfo

Member Type Description
Optional
activatedBy String The name of the user who activated the policy.
activationDate Number The date on which the policy was activated (in milliseconds since Epoch).
detailCode Number Akamai internal activation status codes.
name String The name of the policy.
policyId Number An integer ID that is associated with all versions of a policy.
status Enumeration The activation status for the policy or property. Values include the following: inactive where the policy version has not been activated. No active property versions reference this policy. active where the policy version is currently active (published) and its associated property version is also active. deactivated where the policy version was previously activated but it has been superseded by a more recent activation of another policy version. pending where the policy version is proceeding through the activation workflow. failed where the policy version activation workflow has failed.
statusDetail String Information about the status of an activation operation. This field is not returned when it has no value, and it never has a value for fast activation Cloudlets such as Visitor Prioritization or Phased Release.
version String The version number of the activated policy.

Activation.propertyInfo

Member Type Description
Optional
activatedBy String The name of the user who activated the property.
activationDate Number The date on which the property was activated (in milliseconds since Epoch).
groupId Number Defines the group association for the policy or property. If 0, the policy is not tied to a group and in effect appears in all groups for the account. You must have edit privileges for the group.
name String The name of the property.
status Enumeration The activation status for the policy or property. Values include the following: inactive where the policy version has not been activated. No active property versions reference this policy. active where the policy version is currently active (published) and its associated property version is also active. deactivated where the policy version was previously activated but it has been superseded by a more recent activation of another policy version. pending where the policy version is proceeding through the activation workflow. failed where the policy version activation workflow has failed.
version String The version number of the activated property.

JSON schemas

The following JSON Schemas are available for this API:

Schema Type JSON Schema Name
Create a new policy create-policy.json
Update a policy update-policy.json
Clone an existing policy clone-policy.json
Create or clone a policy version create-nimbus_policy_version-{cloudletType}–1.0.json
Update a policy version update-nimbus_policy_version-{cloudletType}–1.0.json
Create or update a match rule match_rule-{cloudletType}–1.0.json

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

Member Type Description
Optional
title String The title of the JSON schema.
version String The specific version of the JSON schema.
location String The network path for the JSON schema.
description String A description of when the JSON schema is applied.
additionalDescription String Cloudlet-specific information for the JSON schema.

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:

Property Type Description Cloudlets
allowDeny Enumeration If set to allow, the request is sent to origin when all conditions are true. If deny, the request is denied when all conditions are true. If denybranded, the request is denied and rerouted according to the configuration of the Request Control behavior. Request Control
disabled Boolean Optional. If set to true, disables a rule so it is not evaluated against incoming requests. The default setting is false. All
end Integer The end time for this match. Enter the value in UTC in seconds since the epoch. All
forwardSettings Object This property defines data used to construct a new request URL if all conditions are met. If all of the conditions you set are true, then the Edge Server returns an HTTP response from the rewritten URL. The following properties can be used with this object: originId, pathAndQS, percent, and useIncomingQueryString. Audience Segmentation, Forward Rewrite
id Integer Akamai internal use only. All
jsInsertion Boolean If set to true, inserts MediaMath’s JavaScript tag into the requested page. Cloud Marketing, Cloud Marketing Plus
matches Array See matches below. All
matchURL String If using a URL match, this property is the URL that the Cloudlet uses to match the incoming request. Edge Redirector, Forward Rewrite
name String The name of the rule. All
originId String The ID of the Cloudlets Origin requests are forwarded to. To retrieve the originId, run a GET on the /cloudlets/api/v2/properties endpoint. Application Load Balancer, Audience Segmentation, Cloud Marketing, Cloud Marketing Plus, Forward Rewrite, Phased Release
passThroughPercent Number The range 0.000: 99.000 specifies the percentage of requests that pass through to the origin. The value of 100 means the request always passes through to the origin. For Visitor Prioritization, a value of -1 means send everyone to the waiting room. API Prioritization, Visitor Prioritization
pathAndQS String If a value is provided and match conditions are met, this property defines the path/resource/query string to rewrite URL for the incoming request. Audience Segmentation, Forward Rewrite
redirectURL String The URL Edge Redirector redirects the request to. If using useRelativeUrl, you can enter a path for the value. Edge Redirector
start Integer The start time for this match. Enter the value in UTC in seconds since the epoch. All
statusCode Integer The HTTP response status code, which is either 301 (permanent redirect) or 302 (temporary redirect). Edge Redirector
type String The type of Cloudlet the rule is for. For example, the string for Visitor Prioritization is vpMatchRule. All
useIncomingQueryString Boolean If set to true, the Cloudlet includes the query string from the request in the rewritten or forwarded URL. Audience Segmentation, Edge Redirector, Forward Rewrite
useIncomingSchemeAndHost Boolean If set to true, the Cloudlet copies both the protocol/scheme and the hostname from the incoming request to use in the redirect URL. Edge Redirector
useRelativeUrl Enumeration If set to relative_url, takes the path entered for the redirectUrl and sets it in the response’s Location header. The client or browser receiving the request decides which protocol and hostname to use.
If set to copy_scheme_hostname, creates an absolute path by taking the protocol and hostname from the incoming request and combining them with path information entered for the redirectUrl. This absolute path is set in the response’s Location header.
If this property is not included, or is set to none, then the redirectUrl should be fully-qualified URL.
Edge Redirector

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:

Property Type Description
caseSensitive Boolean If true, the match is case sensitive.
checkIPs Enumeration For clientip, continent, countrycode, proxy, and regioncode match types, the part of the request that determines the IP address to use. Values include the connecting IP address (CONNECTING_IP) and the X_Forwarded_For header (XFF_HEADERS). To select both, enter the two values separated by a space delimiter. When both values are included, the connecting IP address is evaluated first.
matchOperator Enumeration Valid entries for this property are contains, exists, and equals.
matchType Enumeration The type of match used. Possible values include the hostname (hostname) or the cookie (cookie). See the Match Type Property section.
matchValue String This depends on the matchType. If the matchType is hostname, then matchValue is the fully qualified domain name, like www.akamai.com. See the examples in the Match Type Property table.
negate Boolean If true, negates the match.
objectMatchValue Object An object used when a rule either includes more complex match criteria, like multiple value attributes, or a range match.
Match value object properties

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

Property Type Description
type Enumeration The array type, which can be one of the following: object, range, or simple. Use the simple option when adding only an array of string-based values.
name Array If using a match type that supports name attributes, enter the value in the incoming request to match on. The following match types support this property: cookie, header, parameter, and query.
nameCaseSensitive Boolean Set to true if the entry for the name property should be evaluated based on case sensitivity.
nameHasRegex Boolean Set to true if the entry for the name property is a regular expression.
nameHasWildcard Boolean Set to true if the entry for the name property includes wildcards.
value Array If using the simple or range array types, enter the value attributes in the incoming request to match on. Valid entries vary by match type. For example, GET and POST are valid entries for the method match type, while any integer is valid for the numberOfFields match type.
valueCaseSensitive Boolean Set to true if the entries for the value property should be evaluated based on case sensitivity.
valueHasRegex Boolean Set to true if the entries for the value property includes a capture group for a regular expression.
valueHasWildcard Boolean Set to true if the entries for the value property includes wildcards.
options Array If using the object type, use this array to list the values to match on.

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).

Match Type Description Example Match Value
all A match of all incoming requests. Note that in the Cloudlets Policy Manager application, this match type is called Default. Not applicable
clientip The IPv4 address or CIDR list to match on. 182.1.0.0
clientipv6 The IPv6 address or CIDR list to match on. 0:0:0:0:0:ffff:b601:0
continent The continent to match on. See Continent Codes for a list of valid codes. SA
cookie The cookie values to match on. name=value1
countrycode The country to match on. See Country Codes for a list of valid codes. US
deviceCharacteristics The device characteristic to match on. See Device Characteristics Match Values for the list of available match values. is_mobile=true
extension (m) The file extensions to match on. jpg png gif
header The parts of the request header to match on. See Matches in Requests and Responses for an example.
hostname (m) The hostnames to match on. www.akamai.com
method The HTTP method used for the request. GET
numberOfFields A match based on the number of form fields included in an incoming request. See Input Validation for an example.
parameter Matches based on the following form parameters: field names and field values. See Input Validation for an example.
path (m) The URL paths to match on. /clothing/children/shoes/shoe1.jpg
protocol The protocol to match on. You can only enter a single value in this field. http
proxy The type of proxy to match on. Values include anonymous, transparent, and both. anonymous
query (m) The query string values to match on. name or name=value1 or name=value1 value2
range A range of two numbers between 1 and 100 (inclusive) for the random value assigned to a user. If the random value assigned to an incoming request falls within this range, the match is true. See Audience Segmentation for an example.
regex The regular expression to match on. ab(c.)d+
regioncode The region within a country to match on, like a state or province. See Region Codes for a list of valid codes. MA
Device characteristics match values

The following values are available for the deviceCharacteristics match type:

Match Value Description
accept_third_party_cookie Indicates whether the device, by default, accepts a cookie set from a pixel in a page of a different domain.
ajax_support_javascript Indicates whether the device supports asynchronous JavaScript and XML (AJAX), a set of programming techniques.
cookie_support Indicates whether the device’s browser supports cookies. However, this device characteristic does not indicate that cookies exist. In addition, if the value is false because the native browser does not support cookies, cookies may be supported using other methods.
full_flash_support Indicates whether the device has full Flash support.
is_mobile Indicates whether the requesting device is a mobile device.
is_tablet Indicates whether the device is a tablet.
is_wireless_device Indicates whether the device is, or is not, wireless. A mobile phone returns true, but a desktop or laptop returns false.

Supported match types by Cloudlet

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

Cloudlet Supported Match Types
Application Load Balancer all, clientip, clientipv6, continent, cookie, countrycode, deviceCharacteristics, extension, header, hostname, method, path, protocol, query, regioncode
API Prioritization clientip, clientipv6, continent, cookie, countrycode, deviceCharacteristics, extension, header, hostname, method, path, protocol, proxy, query, regioncode
Audience Segmentation clientip, clientipv6, continent, cookie, countrycode, deviceCharacteristics, extension, header, hostname, method, path, protocol, proxy, query, range, regex,regioncode
Cloud Marketing clientip, clientipv6, continent, cookie, countrycode, deviceCharacteristics, extension, header, hostname, method, path, protocol, proxy, query, regioncode
Cloud Marketing Plus clientip, clientipv6, continent, cookie, countrycode, deviceCharacteristics, extension, header, hostname, method, path, protocol, proxy, query, regioncode
Edge Redirector all, clientip, clientipv6, continent, cookie, countrycode, deviceCharacteristics, extension, header, hostname, method, path, protocol, proxy, query, regex, regioncode
Forward Rewrite clientip, clientipv6, continent, cookie, countrycode, deviceCharacteristics, extension, header, hostname, method, path, protocol, proxy, query, regex, regioncode
Input Validation clientip, clientipv6, continent, cookie, countrycode, deviceCharacteristics, extension, header, hostname, method, numberOfFields, parameter, path, protocol, proxy, query, regex, regioncode
Phased Release all, clientip, clientipv6, continent, cookie, countrycode, deviceCharacteristics, extension, header, hostname, method, path, protocol, proxy, query, regioncode
Request Control all, clientip, clientipv6, continent, cookie, countrycode, header, method, path, proxy, query, regioncode,
Visitor Prioritization clientip, clientipv6, continent, cookie, countrycode, deviceCharacteristics, extension, header, hostname, method, path, protocol, proxy, query, regioncode

Cloudlet-specific match examples

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

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:

Code Description
200 OK. The operation was successful.
201 Created.
204 No content. Displays when a DELETE operation is successful.
400 Bad Request. Please provide all the required parameters.
403 User is not authenticated.
404 Not Found. The object you were trying to reach could not be found.
409 Validation exception. For example, you might receive this status if a policy already exists with the same policy name. In the case of a duplicate policy name, the message body contains data for the existing policy.
429 Too Many Requests. This code may appear if the API caller is rate limited.
500 There is a problem processing your request. Please try again later. The details are provided in the response body. For example, the request may be missing a required parameter.

Last modified: 1/9/2017