
- Overview
- Resources
- API summary
- List shared policies
- Create a policy
- Get a policy
- Update a policy
- Remove a policy
- Clone a policy as a shared policy
- List policy versions
- Create a policy version
- Get a policy version
- Update a policy version
- Remove a policy version
- List policy activations
- Activate a policy version
- Get status for an activation
- Get active properties
- List Cloudlets
- Data
- Errors
Learn more:
Download this API’s RAML and JSON schema descriptors.
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.
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.
Audience Segmentation. Provides hassle-free traffic segmentation and stickiness without degrading performance. This is often beneficial for A/B and multivariate testing.
See Akamai’s Cloudlets page for the current set of Cloudlets.
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 ID (
gid
orgroupId
) 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 groupId
s.
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.
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.- Create a policy to create a Cloudlet policy using the
groupId
you retrieved from the previous step and the code of a chosen Cloudlet:ER
for Edge RedirectorFR
for Forward RewriteAS
for Audience Segmentation.
The policyId
is returned in the response when the Cloudlet policy is created.
Create a policy version to include a version description and match rules.
Activate a policy version on the staging or production network. This returns an Activation object with the activation
id
.Use the activation
id
to Get status for an activation.- Use the Property Manager API (PAPI) to set up the behavior for the Cloudlet you’re configuring. For more information on the currently supported Cloudlets, see:
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:
List shared policies in Cloudlets API v2 to retrieve and determine the
policyId
that you want to upgrade. It must be an Edge Redirector, Forward Rewrite, or Audience Segmentation policy.Clone a policy as a shared policy using the
policyId
you retrieved previously. As a result a newpolicyId
is created.Activate a policy version on the staging or production network. This returns an Activation object with the activation
id
.Use the activation
id
to Get status for an activation.Use the Property Manager API (PAPI) to edit the behavior for the chosen Cloudlet.
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.
The activation and deactivation processes are asynchronous. To use these operations, you need the version of the policy you want to activate or view.
Follow these steps to check the activation status:
Activate a policy version to retrieve an identifier (
id
) of the activation.Use the
id
to run the Get status for an activation to check the status value. A status value ofSUCCESS
indicates it’s been activated.
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"
}
]
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/ |
Create a policy | POST | /cloudlets/ |
Get a policy | GET | /cloudlets/ |
Update a policy | PUT | /cloudlets/ |
Remove a policy | DELETE | /cloudlets/ |
Clone a policy as a shared policy | POST | /cloudlets/ |
Policy versions | ||
List policy versions | GET | /cloudlets/ |
Create a policy version | POST | /cloudlets/ |
Get a policy version | GET | /cloudlets/ |
Update a policy version | PUT | /cloudlets/ |
Remove a policy version | DELETE | /cloudlets/ |
Activations | ||
List policy activations | GET | /cloudlets/ |
Activate a policy version | POST | /cloudlets/ |
Get status for an activation | GET | /cloudlets/ |
Active properties | ||
Get active properties | GET | /cloudlets/ |
Cloudlets | ||
List Cloudlets | GET | /cloudlets/ |
List shared policies
Returns shared policies that are available within your group.
GET /cloudlets/
Sample: /cloudlets/
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, Forward Rewrite, and Audience Segmentation Cloudlets. 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/
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/
Sample: /cloudlets/
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": {
"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"
}
]
}
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/
Sample: /cloudlets/
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": {
"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"
}
]
}
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/
Sample: /cloudlets/
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/
Sample: /cloudlets/
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": {
"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"
}
]
}
Run these operations in the Cloudlets API v2:
List policies and store the
id
of the relevant policy for use as thepolicyId
request parameter.If you don’t already have the
groupId
, list groups and store the relevantgroupId
.List policy versions and store the relevant
version
values for use asadditionalVersions
.
Run these steps in Cloudlets API v3:
Build the PolicyClone object with the previously stored
groupId
andadditionalVersions
that you want to clone into the new shared policy.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/
Sample: /cloudlets/
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"
}
]
}
If you don’t already have the
policyId
, list shared policies and store theid
of the relevant policy for use as thepolicyId
request parameter.Optionally, set
page
andsize
query parameters to paginate batches of results.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, Forward Rewrite, and Audience Segmentation Cloudlets. If you don’t already have the policyId
, List shared policies and store the relevant id
value.
POST /cloudlets/
Sample: /cloudlets/
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"
}
]
}
If you don’t already have the
policyId
, list shared policies and store theid
of the relevant policy for use as thepolicyId
request parameter.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.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/
Sample: /cloudlets/
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"
}
]
}
List shared policies and store the
id
of the relevant policy for use as thepolicyId
request parameter.List policy versions and store the relevant
version
of the policy from the result set.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/
Sample: /cloudlets/
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"
}
]
}
If you don’t already have the
policyId
, list shared policies and store theid
of the relevant policy for use as thepolicyId
request parameter.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.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/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
policyId |
Integer | 1001 |
Identifies the shared policy. |
version |
Integer | 2001 |
The number of the version. |
Status 204
If you don’t already have the
policyId
, list shared policies and store theid
of the relevant policy for use as thepolicyId
request parameter.List policy versions and store the relevant
version
of the policy from the result set.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/
Sample: /cloudlets/
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"
}
]
}
If you don’t already have the
policyId
, list shared policies and store theid
of the relevant policy for use as thepolicyId
request parameter.Optionally, set
page
andsize
query parameters to paginate batches of results.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. Activating a policy version returns the id
of the activation, which you can store and use to run the Get status for an activation operation to check the status value.
You can activate a policy on each network only after any previous activations have completed, otherwise you get a 409 error.
POST /cloudlets/
Sample: /cloudlets/
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"
}
]
}
If you don’t already have the
policyId
, list shared policies and store theid
of the relevant policy for use as thepolicyId
request parameter.List policy versions and store the relevant
version
for use as apolicyVersion
.Build the Activation object with the
policyVersion
member that you want to activate.POST the object to
/cloudlets/v3/policies/{policyId}/activations
.Optionally, store this activation’s
id
from the response and check its status by running the Get status for an activation operation.
Get status for an activation
Returns the status of an activation. See Activation status.
GET /cloudlets/
Sample: /cloudlets/
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"
}
]
}
List shared policies and store the
id
of the relevant policy for use as thepolicyId
request parameter.If you don’t already have the
id
of the activation from the activation operation’s response, list policy activations and store the relevantid
for use asactivationId
.Optionally, make a GET request to
/cloudlets/v3/policies/{policyId}/activations/{activationId}
.
Get active properties
Returns all active properties that are assigned to the policy.
GET /cloudlets/
Sample: /cloudlets/
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: ActiveProperties
Download schema: policy-active-properties.json
Response body:
{
"page": {
"number": 0,
"size": 1000,
"totalElements": 2,
"totalPages": 1
},
"content": [
{
"groupId": 5,
"id": 1234,
"links": [],
"name": "property",
"network": "PRODUCTION",
"version": 1
},
{
"groupId": 5,
"id": 1233,
"links": [],
"name": "property",
"network": "STAGING",
"version": 1
}
],
"links": [
{
"href": "/cloudlets/v3/policies/101/properties?page=0&size=1000",
"rel": "self"
}
]
}
List Cloudlets
Returns details of Cloudlets that you can create a shared policy for, including a Cloudlet name and Cloudlet type.
GET /cloudlets/
Status 200
application/json
Object type: Cloudlet
Download schema: cloudlet-info.json
Response body:
[
{
"cloudletName": "AUDIENCE_SEGMENTATION",
"cloudletType": "AS"
},
{
"cloudletName": "EDGE_REDIRECTOR",
"cloudletType": "ER"
},
{
"cloudletName": "FORWARD_REWRITE",
"cloudletType": "FR"
}
]
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": {
"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"
}
]
}
Policy members
Member | Type | POST | GET | Description | ||||
---|---|---|---|---|---|---|---|---|
Policy : Contains information about a shared policy. |
||||||||
cloudletType |
Enumeration | ✓ | ✓ | The type of Cloudlet that this policy is for. To see the available Cloudlets, run the List Cloudlets operation. | ||||
createdBy |
String | ✗ | ✓ | The username who created the policy. | ||||
createdDate |
String | ✗ | ✓ | ISO 8601 timestamp indicating when the policy was created. | ||||
current |
Policy. |
✗ | ✓ | 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. |
✗ | ○ | 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. |
✗ | ✓ | 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. |
✗ | ✓ | 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, or null if the policy has no activations. |
||||
latest |
Activation or Null | ✗ | ○ | The status of the most recent activation or deactivation operation for the policy on this network. If the policy has no activations, null is returned. |
||||
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, or null if the policy has no activations. |
||||
latest |
Activation or Null | ✗ | ○ | The status of the most recent activation or deactivation operation for the policy on this network. If the policy has no activations, null is returned. |
||||
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. | ○ | ○ | A list of Cloudlet-specific match rules for this shared policy. Currently, you can create match rules only for the Edge Redirector, Forward Rewrite, and Audience Segmentation Cloudlets. See Match rules in Cloudlets API v2. | ||||
match |
Version. |
✗ | ✓ | 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. |
✗ | ○ | 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. |
|||
additional |
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. |
Cloudlet
Returns details of a Cloudlet that you can create a shared policy for, including a Cloudlet name and Cloudlet type.
Download schema:
cloudlet-info.json
Sample GET response:
[
{
"cloudletName": "AUDIENCE_SEGMENTATION",
"cloudletType": "AS"
},
{
"cloudletName": "EDGE_REDIRECTOR",
"cloudletType": "ER"
},
{
"cloudletName": "FORWARD_REWRITE",
"cloudletType": "FR"
}
]
Cloudlet members
Member | Type | Required | Description |
---|---|---|---|
Cloudlet : Returns details of a Cloudlet that you can create a shared policy for, including a Cloudlet name and Cloudlet type. |
|||
cloudletName |
Enumeration | ✓ | The name of Cloudlet that this policy is for. To see the available Cloudlets, run the List Cloudlets operation. |
cloudletType |
Enumeration | ✓ | The type of Cloudlet that this policy is for. To see the available Cloudlets, run the List Cloudlets operation. |
ActiveProperties
Contains detailed information about all active properties that are assigned to the policy.
Download schema:
policy-active-properties.json
Sample GET response:
{
"page": {
"number": 0,
"size": 1000,
"totalElements": 2,
"totalPages": 1
},
"content": [
{
"groupId": 5,
"id": 1234,
"links": [],
"name": "property",
"network": "PRODUCTION",
"version": 1
},
{
"groupId": 5,
"id": 1233,
"links": [],
"name": "property",
"network": "STAGING",
"version": 1
}
],
"links": [
{
"href": "/cloudlets/v3/policies/101/properties?page=0&size=1000",
"rel": "self"
}
]
}
ActiveProperties members
Member | Type | Required | Description |
---|---|---|---|
ActiveProperties : Contains detailed information about all active properties that are assigned to the policy. |
|||
content |
Active |
○ | Object representing details of property assigned to the policy. |
links |
Active |
○ | Hypermedia links to help navigate through the result set, or to identify the current item whose rel is self . |
page |
Active |
✓ | Contains informational data about pagination. |
ActiveProperties.content[] : Object representing details of property assigned to the policy. |
|||
groupId |
Integer | ✓ | Identifies the group which the property belongs to. |
id |
Integer | ✓ | Identifies the property. |
name |
String | ✓ | Property name. |
network |
Enumeration | ✓ | The networks where you can activate or deactivate the property, either PRODUCTION or STAGING . |
version |
Integer | ✓ | Identifies version of the property. |
ActiveProperties.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. |
ActiveProperties.page : Contains informational data about pagination. |
|||
number |
Integer | ✓ | Specifies the number of the returned page. |
size |
Integer | ✓ | Specifies the number of objects on a page, at least 10 objects. |
totalElements |
Integer | ✓ | Specifies the total number of the available objects. |
totalPages |
Integer | ✓ | Specifies the total number of the available pages. |
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 Activation status. |
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 Activation status for more information. |
500 | Internal server error. |