Cloudlets API v3

Create and activate shared policies for Cloudlets.

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 v3 API allows you to create and view Cloudlet policies and policy versions for shared policies only. In addition, use this API to:

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

  • Delete a Cloudlet policy.

  • Upgrade a legacy policy to a shared policy.

  • View the activation history of a Cloudlet policy.

Cloudlets that use this API

Use this API to set up these Cloudlets:

  • Edge Redirector. Helps you more efficiently manage a 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.

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

Get started

To get started with this API:

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

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named Cloudlets Policy Manager, and set the access level to READ-WRITE.

  • Get help from the Akamai developer community and provide feedback. You can also contact your Akamai representative for support.

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

API concepts

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

  • Policies. For each Cloudlet on your contract, there can be any number of policies. 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. A legacy policy, or a non-shared policy, can only be assigned to one property in Property Manager.

  • Shared policies. A new type of policy that can be used for an unlimited number of properties. This is the only policy type that API version 3 supports. The only interaction with a legacy policy in this API version is to upgrade it to a shared policy. Unlike legacy policies, once a shared policy is activated it’s available on your network for any property. See the Policy object.

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

  • Policy version. A specific revision of a given policy (policyId). Policy 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’re activating a specific version of a Cloudlet policy. See the Version object. If a policy version is being activated or has been activated it is immutable, meaning you can’t modify it.

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

  • Activation. Make a policy version available for use on a given network and across any property in the account. You can only activate shared policies with this API. See the Activation object.

About group IDs

When using this API, your level of access depends on the groups you have access to. If your username isn’t associated with the group ID (gid or groupId) you selected, then the request fails. You need to use the List Groups in Cloudlets API v2 operation in version 2 of this API to retrieve groupIds.

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 company’s own organizational hierarchy.

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

Workflows

Use this workflow to create a Cloudlet policy.

  1. List groups in Cloudlets API v2 to retrieve information about which Cloudlets are associated with the groups you have edit privileges for. You’ll need the groupId values returned by this request when you create a Cloudlet policy.

  2. Create a policy to create a Cloudlet policy using the groupId you retrieved from the previous step and Cloudlet code ER. The policyId is returned in the response when the Cloudlet policy is created.

  3. Create a policy version to include a version description and match rules.

  4. Activate a policy version on the staging or production network. This returns an Activation object with the activation Id.

  5. Use the activation Id to check the status of the operation.

  6. Use the Property Manager API (PAPI) to set up the behavior for the Edge Redirector Cloudlet you’re configuring.

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

Use this workflow to upgrade a Cloudlet policy from the legacy policy type to the shared policy type:

  1. List shared policies in Cloudlets API v2 to retrieve and determine the policyId that you want to upgrade. It must be an Edge Redirector policy.

  2. Clone a policy as a shared policy using the policyId you retrieved previously. As a result a new policyId is created.

  3. Activate a policy version on the staging or production network. This returns an Activation object with the activation Id.

  4. Use the activation Id to Check the status of the operation.

  5. Use the Property Manager API (PAPI) to edit the behavior for the Edge Redirector Cloudlet.

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

Activation status

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. For a given policy and network, the return is the most recently activated and effective policy version.

To use the activation operations, you need to know the version of the policy you want to activate or view. The API responds with these activation status values:

  • IN_PROGRESS. The policy version’s activation is currently in progress.
  • SUCCESS. The policy version activation has succeeded.
  • FAILED. The policy version activation workflow has failed.

Hypermedia

This API provides hypermedia link members to help the client to navigate paginated data. This example within a metadata object shows the set of links to navigate back and forth within the results, to go to the first or last page, or to access the current page. Self is used to go to a particular item in the list. Next is used to go to the next page of results.

"links": [
    {
        "href": "/cloudlets/v3/policies?page=0&size=10",
        "rel": "first"
    },
    {
        "href": "/cloudlets/v3/policies?page=0&size=10",
        "rel": "self"
    },
    {
        "href": "/cloudlets/v3/policies?page=1&size=10",
        "rel": "next"
    },
    {
        "href": "/cloudlets/v3/policies?page=110&size=10",
        "rel": "last"
    }
]

Concurrency control

There’s concurrency control on the activation and deactivation processes. You can’t run subsequent activations on a given network for the same policy if the previous activation is still running. You’ll receive a 409 error if you do this. Single policies can be activated on a given network only one at a time. Activate a policy version is the only operation with concurrency control.

Asynchronous processes

The activation and deactivation processes are asynchronous. The Activate a policy version operation returns an identifier of the activation. You can use this identifier to run the Get an operation’s status and check whether it’s in-progress, success, or failed.

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Policies  
List shared policies GET /cloudlets/v3/policies{?page,size}
Create a policy POST /cloudlets/v3/policies
Get a policy GET /cloudlets/v3/policies/{policyId}
Update a policy PUT /cloudlets/v3/policies/{policyId}
Remove a policy DELETE /cloudlets/v3/policies/{policyId}
Clone a policy as a shared policy POST /cloudlets/v3/policies/{policyId}/clone
Policy versions  
List policy versions GET /cloudlets/v3/policies/{policyId}/versions{?page,size}
Create a policy version POST /cloudlets/v3/policies/{policyId}/versions
Get a policy version GET /cloudlets/v3/policies/{policyId}/versions/{version}
Update a policy version PUT /cloudlets/v3/policies/{policyId}/versions/{version}
Remove a policy version DELETE /cloudlets/v3/policies/{policyId}/versions/{version}
Activations  
List policy activations GET /cloudlets/v3/policies/{policyId}/activations{?page,size}
Activate a policy version POST /cloudlets/v3/policies/{policyId}/activations
Get an activation’s status GET /cloudlets/v3/policies/{policyId}/activations/{activationId}

List shared policies

Returns shared policies that are available within your group.

GET /cloudlets/v3/policies{?page,size}

Sample: /cloudlets/v3/policies?page=3&size=100

Parameter Type Sample Description
Optional query parameters
page Integer 3 Specifies a page number for batched results, starting at zero.
size Integer 100 Specifies the number of objects on a page, at least 10 objects.

Status 200 application/json

Object type: Policy

Download schema: policies.json

Response body:

{
    "page": {
        "number": 0,
        "size": 10,
        "totalElements": 1103,
        "totalPages": 111
    },
    "content": [
        {
            "cloudletType": "ER",
            "createdBy": "jsmith",
            "createdDate": "2020-10-01T12:35:22.500Z",
            "description": "ER policy for static assets",
            "groupId": 5,
            "id": 1001,
            "modifiedBy": "sjones",
            "modifiedDate": "2020-10-01T12:35:22.500Z",
            "name": "static_assets_redirector",
            "policyType": "SHARED",
            "currentActivations": {
                "production": {
                    "latest": {
                        "createdBy": "sjones",
                        "createdDate": "2020-10-01T12:35:24.520Z",
                        "finishDate": "2020-10-01T12:35:25.962Z",
                        "id": 300001,
                        "network": "PRODUCTION",
                        "operation": "ACTIVATION",
                        "policyId": 1001,
                        "status": "SUCCESS",
                        "policyVersion": 1,
                        "links": [
                            {
                                "href": "/cloudlets/v3/policies/1001/activations/300001",
                                "rel": "self"
                            }
                        ]
                    },
                    "effective": {
                        "createdBy": "sjones",
                        "createdDate": "2020-10-01T12:35:24.520Z",
                        "finishDate": "2020-10-01T12:35:25.962Z",
                        "id": 300001,
                        "network": "PRODUCTION",
                        "operation": "ACTIVATION",
                        "policyId": 1001,
                        "status": "SUCCESS",
                        "policyVersion": 1,
                        "links": [
                            {
                                "href": "/cloudlets/v3/policies/1001/activations/300001",
                                "rel": "self"
                            }
                        ]
                    }
                },
                "staging": {
                    "effective": null,
                    "latest": null
                }
            },
            "links": [
                {
                    "href": "/cloudlets/v3/policies/1001",
                    "rel": "self"
                }
            ]
        }
    ],
    "links": [
        {
            "href": "/cloudlets/v3/policies?page=0&size=10",
            "rel": "first"
        },
        {
            "href": "/cloudlets/v3/policies?page=0&size=10",
            "rel": "self"
        },
        {
            "href": "/cloudlets/v3/policies?page=1&size=10",
            "rel": "next"
        },
        {
            "href": "/cloudlets/v3/policies?page=110&size=10",
            "rel": "last"
        }
    ]
}

Create a policy

Creates a shared policy for a specific Cloudlet type. Currently, you can create a policy only for the Edge Redirector Cloudlet. You can then add match rules by creating a policy version. If a policy already exists with the same policy name, you receive a 409 status response that contains data for the existing policy.

POST /cloudlets/v3/policies

Content-Type: application/json

Object type: Policy

Download schema: new-policy.json

Request body:

{
    "cloudletType": "ER",
    "description": "ER policy for static assets",
    "groupId": 5,
    "name": "static_assets_redirector"
}

Status 201 application/json

Object type: Policy

Download schema: policy.json

Response body:

{
    "cloudletType": "ER",
    "createdBy": "jsmith",
    "createdDate": "2020-10-01T12:35:22.500Z",
    "description": "ER policy for static assets",
    "groupId": 5,
    "id": 1001,
    "modifiedBy": "sjones",
    "modifiedDate": "2020-10-01T12:35:22.500Z",
    "name": "static_assets_redirector",
    "policyType": "SHARED",
    "currentActivations": {
        "production": {
            "latest": null,
            "effective": null
        },
        "staging": {
            "effective": null,
            "latest": null
        }
    },
    "links": [
        {
            "href": "/cloudlets/v3/policies/1001",
            "rel": "self"
        }
    ]
}

Get a policy

Returns information about a shared policy, including its activation status on the staging and production networks. If you don’t already have the policyId, list shared policies and store the relevant id value.

GET /cloudlets/v3/policies/{policyId}

Sample: /cloudlets/v3/policies/1001

Parameter Type Sample Description
URL path parameters
policyId Integer 1001 Identifies the policy.

Status 200 application/json

Object type: Policy

Download schema: policy.json

Response body:

{
    "cloudletType": "ER",
    "createdBy": "jsmith",
    "createdDate": "2020-10-01T12:35:22.500Z",
    "description": "ER policy for static assets",
    "groupId": 5,
    "id": 1001,
    "modifiedBy": "sjones",
    "modifiedDate": "2020-10-01T12:35:22.500Z",
    "name": "static_assets_redirector",
    "policyType": "SHARED",
    "currentActivations": {
        "production": {
            "latest": null,
            "effective": {
                "createdBy": "sjones",
                "createdDate": "2020-10-01T12:35:24.520Z",
                "finishDate": "2020-10-01T12:35:25.962Z",
                "id": 300001,
                "network": "PRODUCTION",
                "operation": "ACTIVATION",
                "policyId": 1001,
                "status": "SUCCESS",
                "policyVersion": 1,
                "links": [
                    {
                        "href": "/cloudlets/v3/policies/1001/activations/300001",
                        "rel": "self"
                    }
                ]
            }
        },
        "staging": {
            "effective": null,
            "latest": null
        }
    },
    "links": [
        {
            "href": "/cloudlets/v3/policies/1001",
            "rel": "self"
        }
    ]
}

Update a policy

Updates an existing policy. If you don’t already have the policyId, list shared policies and store the relevant id value.

PUT /cloudlets/v3/policies/{policyId}

Sample: /cloudlets/v3/policies/1001

Content-Type: application/json

Object type: Policy

Download schema: update-policy.json

Request body:

{
    "description": "ER policy for static assets",
    "groupId": 5
}
Parameter Type Sample Description
URL path parameters
policyId Integer 1001 Identifies the policy.

Status 200 application/json

Object type: Policy

Download schema: policy.json

Response body:

{
    "cloudletType": "ER",
    "createdBy": "jsmith",
    "createdDate": "2020-10-01T12:35:22.500Z",
    "description": "ER policy for static assets",
    "groupId": 5,
    "id": 1001,
    "modifiedBy": "sjones",
    "modifiedDate": "2020-10-01T12:35:22.500Z",
    "name": "static_assets_redirector",
    "policyType": "SHARED",
    "currentActivations": {
        "production": {
            "latest": null,
            "effective": {
                "createdBy": "sjones",
                "createdDate": "2020-10-01T12:35:24.520Z",
                "finishDate": "2020-10-01T12:35:25.962Z",
                "id": 300001,
                "network": "PRODUCTION",
                "operation": "ACTIVATION",
                "policyId": 1001,
                "status": "SUCCESS",
                "policyVersion": 1,
                "links": [
                    {
                        "href": "/cloudlets/v3/policies/1001/activations/300001",
                        "rel": "self"
                    }
                ]
            }
        },
        "staging": {
            "effective": null,
            "latest": null
        }
    },
    "links": [
        {
            "href": "/cloudlets/v3/policies/1001",
            "rel": "self"
        }
    ]
}

Remove a policy

Deletes an existing Cloudlets policy. If you don’t already have the policyId, list shared policies and store the relevant id value. You can’t delete a policy if any of its versions is active or being activated on the staging or production networks.

DELETE /cloudlets/v3/policies/{policyId}

Sample: /cloudlets/v3/policies/1001

Parameter Type Sample Description
URL path parameters
policyId Integer 1001 Identifies the policy.

Status 204

Clone a policy as a shared policy

Clones the staging, production, and last modified versions of a legacy or shared policy into a new shared policy. You can also specify any additional versions that you want to clone into the new shared policy. If you don’t already have the policyId, list shared policies and store the relevant id value.

POST /cloudlets/v3/policies/{policyId}/clone

Sample: /cloudlets/v3/policies/1001/clone

Content-Type: application/json

Object type: PolicyClone

Download schema: policy-clone-request.json

Request body:

{
    "additionalVersions": [
        3,
        5
    ],
    "groupId": 1,
    "newName": "static_assets_redirector_shared"
}
Parameter Type Sample Description
URL path parameters
policyId Integer 1001 Identifies the policy.

Status 200 application/json

Object type: Policy

Download schema: policy.json

Response body:

{
    "cloudletType": "ER",
    "createdBy": "jsmith",
    "createdDate": "2020-10-01T12:35:22.500Z",
    "description": "ER policy for static assets",
    "groupId": 5,
    "id": 1001,
    "modifiedBy": "sjones",
    "modifiedDate": "2020-10-01T12:35:22.500Z",
    "name": "static_assets_redirector",
    "policyType": "SHARED",
    "currentActivations": {
        "production": {
            "latest": null,
            "effective": {
                "createdBy": "sjones",
                "createdDate": "2020-10-01T12:35:24.520Z",
                "finishDate": "2020-10-01T12:35:25.962Z",
                "id": 300001,
                "network": "PRODUCTION",
                "operation": "ACTIVATION",
                "policyId": 1001,
                "status": "SUCCESS",
                "policyVersion": 1,
                "links": [
                    {
                        "href": "/cloudlets/v3/policies/1001/activations/300001",
                        "rel": "self"
                    }
                ]
            }
        },
        "staging": {
            "effective": null,
            "latest": null
        }
    },
    "links": [
        {
            "href": "/cloudlets/v3/policies/1001",
            "rel": "self"
        }
    ]
}

Run these operations in the Cloudlets API v2:

  1. List policies and store the id of the relevant policy for use as the policyId request parameter.

  2. If you don’t already have the groupId, list groups and store the relevant groupId.

  3. List policy versions and store the relevant version values for use as additionalVersions.

Run these steps in Cloudlets API v3:

  1. Build the PolicyClone object with the previously stored groupId and additionalVersions that you want to clone into the new shared policy.

  2. Using Cloudlets API v2, POST the object to /cloudlets/v3/policies/{policyId}/clone.

List policy versions

Returns information about all versions of a shared policy.

GET /cloudlets/v3/policies/{policyId}/versions{?page,size}

Sample: /cloudlets/v3/policies/1001/versions?page=3&size=100

Parameter Type Sample Description
URL path parameters
policyId Integer 1001 Identifies the shared policy.
Optional query parameters
page Integer 3 Specifies a page number for batched results, starting at zero.
size Integer 100 Specifies the number of objects on a page—at least 10 objects.

Status 200 application/json

Object type: Version

Download schema: policy-versions.json

Response body:

{
    "page": {
        "number": 0,
        "size": 1000,
        "totalElements": 1,
        "totalPages": 1
    },
    "content": [
        {
            "createdBy": "jsmith",
            "createdDate": "2020-10-01T12:35:22.500Z",
            "description": "Initial version",
            "id": 2001,
            "modifiedBy": "jsmith",
            "modifiedDate": "2020-10-01T12:35:22.500Z",
            "policyId": 101,
            "version": 1,
            "links": [
                {
                    "href": "/cloudlets/v3/policies/101/versions/1",
                    "rel": "self"
                }
            ]
        }
    ],
    "links": [
        {
            "href": "/cloudlets/v3/policies/101/versions?page=0&size=1000",
            "rel": "self"
        }
    ]
}
  1. If you don’t already have the policyId, list shared policies and store the id of the relevant policy for use as the policyId request parameter.

  2. Optionally, set page and size query parameters to paginate batches of results.

  3. Make a GET request to /cloudlets/v3/policies/{policyId}/versions{?page,size}.

Create a policy version

Creates a policy version, including match rules for a Cloudlet that you’re using. Currently, you can create match rules only for the Edge Redirector Cloudlet. If you don’t already have the policyId, List shared policies and store the relevant id value.

POST /cloudlets/v3/policies/{policyId}/versions

Sample: /cloudlets/v3/policies/1001/versions

Content-Type: application/json

Object type: Version

Download schema: new-policy-version.json

Request body:

{
    "description": "Initial version",
    "matchRules": [
        {
            "end": 0,
            "name": "Redirect images",
            "matchURL": "/images/*",
            "redirectURL": "/static/images/*",
            "start": 0,
            "statusCode": 302,
            "type": "erMatchRule",
            "useIncomingQueryString": true,
            "useRelativeUrl": "relative_url"
        }
    ]
}
Parameter Type Sample Description
URL path parameters
policyId Integer 1001 Identifies the shared policy.

Status 201 application/json

Object type: Version

Download schema: policy-version.json

Response body:

{
    "createdBy": "jsmith",
    "createdDate": "2020-10-02T13:48:27.018Z",
    "modifiedBy": "jsmith",
    "modifiedDate": "2020-10-02T13:48:27.018Z",
    "description": "Initial version",
    "id": 2002,
    "immutable": false,
    "policyId": 1001,
    "version": 1,
    "matchRulesWarnings": [],
    "matchRules": [
        {
            "type": "erMatchRule",
            "id": 0,
            "name": "Redirect images",
            "start": 0,
            "end": 0,
            "matchURL": "/images/*",
            "akaRuleId": "ac0ca0af44f57683",
            "statusCode": 302,
            "redirectURL": "/static/images/*",
            "useIncomingQueryString": true,
            "useRelativeUrl": "relative_url"
        }
    ]
}
  1. If you don’t already have the policyId, list shared policies and store the id of the relevant policy for use as the policyId request parameter.

  2. Build the Version object with matchRules for your Cloudlet type. Currently, you can add match rules only for the Edge Redirector Cloudlet. See Match rules.

  3. POST the object to /cloudlets/v3/policies/{policyId}/versions.

Get a policy version

Returns information about a shared policy version, including match rules for a Cloudlet that you’re using and whether its locked for changes.

GET /cloudlets/v3/policies/{policyId}/versions/{version}

Sample: /cloudlets/v3/policies/1001/versions/2001

Parameter Type Sample Description
URL path parameters
policyId Integer 1001 Identifies the shared policy.
version Integer 2001 The number of the version.

Status 200 application/json

Object type: Version

Download schema: policy-version.json

Response body:

{
    "createdBy": "jsmith",
    "createdDate": "2020-10-02T13:48:27.018Z",
    "modifiedBy": "jsmith",
    "modifiedDate": "2020-10-02T13:48:27.018Z",
    "description": "Initial version",
    "id": 2002,
    "immutable": false,
    "policyId": 1001,
    "version": 1,
    "matchRulesWarnings": [],
    "matchRules": [
        {
            "type": "erMatchRule",
            "id": 0,
            "name": "Redirect images",
            "start": 0,
            "end": 0,
            "matchURL": "/images/*",
            "akaRuleId": "ac0ca0af44f57683",
            "statusCode": 302,
            "redirectURL": "/static/images/*",
            "useIncomingQueryString": true,
            "useRelativeUrl": "relative_url"
        }
    ]
}
  1. List shared policies and store the id of the relevant policy for use as the policyId request parameter.

  2. List policy versions and store the relevant version of the policy from the result set.

  3. Make a GET request to cloudlets/v3/policies/{policyId}/versions/{version}.

Update a policy version

Updates the description and match rules for a policy version.

PUT /cloudlets/v3/policies/{policyId}/versions/{version}

Sample: /cloudlets/v3/policies/1001/versions/2001

Content-Type: application/json

Object type: Version

Download schema: update-policy-version.json

Request body:

{
    "description": "Initial version",
    "matchRules": [
        {
            "end": 0,
            "name": "Redirect images",
            "matchURL": "/images/*",
            "redirectURL": "/static/images/*",
            "start": 0,
            "statusCode": 302,
            "type": "erMatchRule",
            "useIncomingQueryString": true,
            "useRelativeUrl": "relative_url"
        }
    ]
}
Parameter Type Sample Description
URL path parameters
policyId Integer 1001 Identifies the shared policy.
version Integer 2001 The number of the version.

Status 200 application/json

Object type: Version

Download schema: policy-version.json

Response body:

{
    "createdBy": "jsmith",
    "createdDate": "2020-10-02T13:48:27.018Z",
    "modifiedBy": "jsmith",
    "modifiedDate": "2020-10-02T13:48:27.018Z",
    "description": "Initial version",
    "id": 2002,
    "immutable": false,
    "policyId": 1001,
    "version": 1,
    "matchRulesWarnings": [],
    "matchRules": [
        {
            "type": "erMatchRule",
            "id": 0,
            "name": "Redirect images",
            "start": 0,
            "end": 0,
            "matchURL": "/images/*",
            "akaRuleId": "ac0ca0af44f57683",
            "statusCode": 302,
            "redirectURL": "/static/images/*",
            "useIncomingQueryString": true,
            "useRelativeUrl": "relative_url"
        }
    ]
}
  1. If you don’t already have the policyId, list shared policies and store the id of the relevant policy for use as the policyId request parameter.

  2. Build the Version object with matchRules for your Cloudlet type. Currently, you can add match rules only for the Edge Redirector Cloudlet. See Match rules.

  3. PUT the object to /cloudlets/v3/policies/{policyId}/versions.

Remove a policy version

Deletes a version of a shared policy. You can’t delete a policy if it’s active on the staging or production network. When you remove a policy version, version numbers aren’t reallocated. For example, a policy has 15 versions, and you delete versions 14 and 15. The next version created would be 16, not 14.

DELETE /cloudlets/v3/policies/{policyId}/versions/{version}

Sample: /cloudlets/v3/policies/1001/versions/2001

Parameter Type Sample Description
URL path parameters
policyId Integer 1001 Identifies the shared policy.
version Integer 2001 The number of the version.

Status 204

  1. If you don’t already have the policyId, list shared policies and store the id of the relevant policy for use as the policyId request parameter.

  2. List policy versions and store the relevant version of the policy from the result set.

  3. Make a DELETE request to /cloudlets/v3/policies/{policyId}/versions/{version}.

List policy activations

Returns the complete activation history for the selected policy.

GET /cloudlets/v3/policies/{policyId}/activations{?page,size}

Sample: /cloudlets/v3/policies/1001/activations?page=3&size=100

Parameter Type Sample Description
URL path parameters
policyId Integer 1001 Identifies the shared policy.
Optional query parameters
page Integer 3 Specifies a page number for batched results, starting at zero.
size Integer 100 Specifies the number of objects on a page—at least 10 objects.

Status 200 application/json

Object type: Activation

Download schema: policy-activations.json

Response body:

{
    "page": {
        "number": 0,
        "size": 1000,
        "totalElements": 4,
        "totalPages": 1
    },
    "content": [
        {
            "createdBy": "sjones",
            "createdDate": "2020-10-01T12:35:24.520Z",
            "finishDate": "2020-10-01T12:35:25.962Z",
            "id": 300001,
            "network": "PRODUCTION",
            "operation": "ACTIVATION",
            "policyId": 1001,
            "status": "IN_PROGRESS",
            "policyVersion": 1,
            "links": [
                {
                    "href": "/cloudlets/v3/policies/1001/activations/300001",
                    "rel": "self"
                }
            ]
        }
    ],
    "links": [
        {
            "href": "/cloudlets/v3/policies/1001/activations?page=0&size=1000",
            "rel": "self"
        }
    ]
}
  1. If you don’t already have the policyId, list shared policies and store the id of the relevant policy for use as the policyId request parameter.

  2. Optionally, set page and size query parameters to paginate batches of results.

  3. Make a POST request to /cloudlets/v3/policies/{policyId}/activations{?page,size}.

Activate a policy version

Asynchronously activates or deactivates the selected Cloudlet policy version on the staging or production networks. When a policy version becomes active on the network, the previously active version gets automatically deactivated. You can store the id of this activation and check its status by running the get the activation’s status operation.

POST /cloudlets/v3/policies/{policyId}/activations

Sample: /cloudlets/v3/policies/1001/activations

Content-Type: application/json

Object type: Activation

Download schema: new-policy-activation.json

Request body:

{
    "network": "PRODUCTION",
    "operation": "ACTIVATION",
    "policyVersion": 1
}
Parameter Type Sample Description
URL path parameters
policyId Integer 1001 Identifies the shared policy.

Status 202 application/json

Object type: Activation

Download schema: policy-activation.json

Response body:

{
    "createdBy": "sjones",
    "createdDate": "2020-10-01T12:35:24.520Z",
    "finishDate": "2020-10-01T12:35:25.962Z",
    "id": 300001,
    "network": "PRODUCTION",
    "operation": "ACTIVATION",
    "policyId": 1001,
    "status": "SUCCESS",
    "policyVersion": 1,
    "links": [
        {
            "href": "/cloudlets/v3/policies/1001/activations/300001",
            "rel": "self"
        }
    ]
}
  1. If you don’t already have the policyId, list shared policies and store the id of the relevant policy for use as the policyId request parameter.

  2. List policy versions and store the relevant version for use as a policyVersion.

  3. Build the Activation object with the policyVersion member that you want to activate.

  4. POST the object to /cloudlets/v3/policies/{policyId}/activations.

  5. Optionally, store this activation’s id from the response and check its status by running the Get an activation’s status operation.

Get an activation’s status

Returns the status of an activation. See Activation status.

GET /cloudlets/v3/policies/{policyId}/activations/{activationId}

Sample: /cloudlets/v3/policies/1001/activations/3001

Parameter Type Sample Description
URL path parameters
policyId Integer 1001 Identifies the shared policy.
activationId Integer 3001 Identifies the policy activation.

Status 200 application/json

Object type: Activation

Download schema: policy-activation.json

Response body:

{
    "createdBy": "sjones",
    "createdDate": "2020-10-01T12:35:24.520Z",
    "finishDate": "2020-10-01T12:35:25.962Z",
    "id": 300001,
    "network": "PRODUCTION",
    "operation": "ACTIVATION",
    "policyId": 1001,
    "status": "SUCCESS",
    "policyVersion": 1,
    "links": [
        {
            "href": "/cloudlets/v3/policies/1001/activations/300001",
            "rel": "self"
        }
    ]
}
  1. List shared policies and store the id of the relevant policy for use as the policyId request parameter.

  2. If you don’t already have the id of the activation from the activation operation’s response, list policy activations and store the relevant id for use as activationId.

  3. Optionally, make a GET request to /cloudlets/v3/policies/{policyId}/activations/{activationId}.

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it either triggers an error, or is ignored.

Policy

Contains information about a shared policy.

Download schema: new-policy.json, policy.json

Sample POST request:

{
    "cloudletType": "ER",
    "description": "ER policy for static assets",
    "groupId": 5,
    "name": "static_assets_redirector"
}

Sample GET response:

{
    "cloudletType": "ER",
    "createdBy": "jsmith",
    "createdDate": "2020-10-01T12:35:22.500Z",
    "description": "ER policy for static assets",
    "groupId": 5,
    "id": 1001,
    "modifiedBy": "sjones",
    "modifiedDate": "2020-10-01T12:35:22.500Z",
    "name": "static_assets_redirector",
    "policyType": "SHARED",
    "currentActivations": {
        "production": {
            "latest": null,
            "effective": {
                "createdBy": "sjones",
                "createdDate": "2020-10-01T12:35:24.520Z",
                "finishDate": "2020-10-01T12:35:25.962Z",
                "id": 300001,
                "network": "PRODUCTION",
                "operation": "ACTIVATION",
                "policyId": 1001,
                "status": "SUCCESS",
                "policyVersion": 1,
                "links": [
                    {
                        "href": "/cloudlets/v3/policies/1001/activations/300001",
                        "rel": "self"
                    }
                ]
            }
        },
        "staging": {
            "effective": null,
            "latest": null
        }
    },
    "links": [
        {
            "href": "/cloudlets/v3/policies/1001",
            "rel": "self"
        }
    ]
}

Policy members

Member Type POST GET Description
Policy: Contains information about a shared policy.
cloudletType String The type of Cloudlet that this policy is for. Currently, you can create shared policies only for the Edge Redirector Cloudlet (ER). See List Cloudlets with Cloudlets API v2.
createdBy String The username who created the policy.
createdDate String ISO 8601 timestamp indicating when the policy was created.
currentActivations Policy.currentActivations Information about the active policy version that’s currently in use and the status of the most recent activation or deactivation operation on the policy’s versions for the production and staging networks.
description String A human-readable label for the policy.
groupId Integer Identifies the group where you want to create the policy. See About group IDs.
id Integer Identifies the policy.
links Policy.links[] Hypermedia links to help navigate through the result set, or to identify the current item whose rel is self.
modifiedBy String The username who last modified the policy.
modifiedDate String ISO 8601 timestamp indicating when the policy was last modified.
name String The name of the policy. You use this value to refer to this policy in Property Manager.
policyType Enumeration The type of policy that you want to create. This API lets you create only SHARED policies.
Policy.currentActivations: Information about the active policy version that’s currently in use and the status of the most recent activation or deactivation operation on the policy’s versions for the production and staging networks.
production Policy.currentActivations.production The policy version number that’s currently in use on this network and the status of the most recent activation or deactivation operation for this policy’s versions.
staging Policy.currentActivations.staging The policy version number that’s currently in use on this network and the status of the most recent activation or deactivation operation for this policy’s versions.
Policy.currentActivations.production: The policy version number that’s currently in use on this network and the status of the most recent activation or deactivation operation for this policy’s versions.
effective Activation or Null The status of the activation that’s currently in use on this network.
latest Activation or Null The status of the most recent activation or deactivation operation for the policy version on this network.
Policy.currentActivations.staging: The policy version number that’s currently in use on this network and the status of the most recent activation or deactivation operation for this policy’s versions.
effective Activation or Null The status of the activation that’s currently in use on this network.
latest Activation or Null The status of the most recent activation or deactivation operation for the policy version on this network.
Policy.links[]: Hypermedia links to help navigate through the result set, or to identify the current item whose rel is self.
href String A relative path to the currently requested object or a specific page of the result set.
rel String The relationship between the current and linked result sets. self links to the current result set, while first, next, and last link to different sets of paginated data.

Version

Contains information about a policy version.

Download schema: update-policy-version.json, policy-version.json

Sample PUT request:

{
    "description": "Initial version",
    "matchRules": [
        {
            "end": 0,
            "name": "Redirect images",
            "matchURL": "/images/*",
            "redirectURL": "/static/images/*",
            "start": 0,
            "statusCode": 302,
            "type": "erMatchRule",
            "useIncomingQueryString": true,
            "useRelativeUrl": "relative_url"
        }
    ]
}

Sample GET response:

{
    "createdBy": "jsmith",
    "createdDate": "2020-10-02T13:48:27.018Z",
    "modifiedBy": "jsmith",
    "modifiedDate": "2020-10-02T13:48:27.018Z",
    "description": "Initial version",
    "id": 2002,
    "immutable": false,
    "policyId": 1001,
    "version": 1,
    "matchRulesWarnings": [],
    "matchRules": [
        {
            "type": "erMatchRule",
            "id": 0,
            "name": "Redirect images",
            "start": 0,
            "end": 0,
            "matchURL": "/images/*",
            "akaRuleId": "ac0ca0af44f57683",
            "statusCode": 302,
            "redirectURL": "/static/images/*",
            "useIncomingQueryString": true,
            "useRelativeUrl": "relative_url"
        }
    ]
}

Version members

Member Type PUT GET Description
Version: Contains information about a policy version.
createdBy String The username who created the policy version.
createdDate String ISO 8601 timestamp indicating when the policy version was created.
description String A human-readable label for the version.
id Integer Identifies the policy version. You don’t use this identifier to refer to a policy version in any operation. Use the version member for this purpose.
immutable Boolean If true, this policy version is active or in the process of being activated, and you can’t modify it.
matchRules An array of match rules for an Edge Redirector. A list of Cloudlet-specific match rules for this shared policy. Currently, you can create match rules only for the Edge Redirector Cloudlet. See Match rules in Cloudlets API v2.
matchRulesWarnings Version.matchRulesWarnings[] A list of warnings about the version’s match rules.
modifiedBy String The username who last modified the policy version.
modifiedDate String ISO 8601 timestamp indicating when the policy version was last modified.
policyId Integer Identifies the shared policy.
version Integer The number of the policy version.
Version.matchRulesWarnings[]: A list of warnings about the version’s match rules.
detail String A detailed description of the warning.
jsonPointer String A JSON pointer to the warned data.
title String The title of the warning.
type String A link to detailed information about the warning type.

Activation

Contains information about an activation of a policy version.

Download schema: new-policy-activation.json, policy-activation.json

Sample POST:

{
    "network": "PRODUCTION",
    "operation": "ACTIVATION",
    "policyVersion": 1
}

Activation members

Member Type POST GET Description
Activation: Contains information about an activation of a policy version.
createdBy String The username who created the activation.
createdDate String ISO 8601 timestamp indicating when the activation was created.
failureDetails String A detailed description of the reason why the activation failed.
finishDate String, Null ISO 8601 timestamp indicating when the activation ended, either successfully or unsuccessfully. You can check details of unsuccessful attempts in failureDetails.
id Integer Identifies the activation.
links Activation.links[] Hypermedia links to help navigate through the result set, or to identify the current item whose rel is self.
network Enumeration The networks where you can activate or deactivate the policy version, either PRODUCTION or STAGING.
operation Enumeration The operations that you can perform on a policy version, either ACTIVATION or DEACTIVATION.
policyId Integer Identifies the shared policy.
policyVersion Integer Identifies the policy version.
status Enumeration The status of the operation, either IN_PROGRESS,SUCCESS, or FAILED.
Activation.links[]: Hypermedia links to help navigate through the result set, or to identify the current item whose rel is self.
href String A relative path to the currently requested object or a specific page of the result set.
rel String The relationship between the current and linked result sets. self links to the current result set, while first, next, and last link to different sets of paginated data.

PolicyClone

Contains information that you need to provide to clone a policy’s versions as a shared policy.

Download schema: policy-clone-request.json

Sample POST:

{
    "additionalVersions": [
        3,
        5
    ],
    "groupId": 1,
    "newName": "static_assets_redirector_shared"
}

PolicyClone members

Member Type Required Description
PolicyClone: Contains information that you need to provide to clone a policy’s versions as a shared policy.
additionalVersions Array Any additional versions that you want to clone into the new shared policy.
groupId Integer Identifies the group where you want to create the shared policy. See About group IDs.
newName String The name of the new shared policy.

Errors

This section provides details on the data object that reflects the API’s common response to error cases. It also lists the API’s range of response status codes for both error and success cases.

Error responses

In error cases, the API responds with JSON objects that follow the HTTP Problem Details. This sample shows a bad request error, where the title is a descriptive label for the overall problem, and the instance may be useful if you need to communicate the problem to your Akamai support representative. It also includes an optional errors array that lists potentially more than one problem detected in the request.

{
    "status": 400,
    "title": "Validation failed",
    "instance": "e943f013-400a-45cf-8fd9-a2d1a37fefa1",
    "type": "[URI defining type]",
    "errors": [
        {
            "detail": "description must not be null",
            "title": "Constraint validation failed",
            "invalidField": "description",
            "invalidValue": null
        }
    ]
}

HTTP status codes

This section lists the full range of response codes the API may generate.

Code Description
200 The operation was successful.
201 Resource successfully created.
202 Request accepted but not yet processed. Typically returned for asynchronous policy version activation operations. See Asynchronous processes.
204 Successful DELETE operation.
400 Invalid request parameters, or problems parsing or validating the request object.
401 Authentication failure. See Get started for more information.
403 No permission to access this resource. See Get started to make sure you have permission to access all the functionality you need.
404 Resource not found.
409 Conflict with the current state of the resource. See Concurrency control for more information.
500 Internal server error.