
- Overview
- Resources
- API summary
- List cloudlets
- Get a cloudlet
- List groups
- Get a group
- List policies
- Create a policy
- Get a policy
- Update a policy
- Remove a policy
- List policy versions
- Create a new policy version
- Get a policy version
- Update a policy version
- Remove a policy version
- Add a version rule
- Get a version rule
- Update a version rule
- List associated properties
- Get associated properties for a policy
- List conditional origins
- Get a conditional origin
- Create a load balancing configuration
- Update a load balancing configuration
- List load balancing versions
- Create a load balancing version
- Get a load balancing version
- Update a load balancing version
- List current load balancing activations
- List activations for a load balancing configuration
- Activate a load balancing version
- List policy activations
- Activate a policy version
- Get a schema
- List schemas per Cloudlet
- Data
- Match rules
- Errors
Cloudlets API v2
Create and manage policies and policy versions for Cloudlet applications on the edge.
Learn more:
Overview
Cloudlets are value-added applications that complement Akamai’s core delivery solutions to solve specific business challenges. Cloudlets bring a site’s business logic closer to the end user by placing it on the “edge” of the content delivery platform.
The Cloudlets v2 API allows you to create and view Cloudlet policies and policy versions. In addition, use this API to
activate a Cloudlet policy version on either the staging or production networks.
delete a Cloudlet policy.
view group-level information about a particular Cloudlet.
Cloudlets that use this API
Use this API to set up the following Cloudlets:
Application Load Balancer: provides intelligent, scalable traffic management across physical, virtual, and cloud-hosted data centers without requiring the origin to send load feedback. This Cloudlet can automatically detect load conditions and route traffic to the optimal data source while maintaining custom routing policies and consistent visitor session behavior for your visitors.
API Prioritization: allows you to specify, for applications that call resources of various formats (like JSON or XML), which calls are given priority and are sent to the origin during high-demand situations. Based on information in the inbound request, you configure the rules that determine which calls are prioritized.
Audience Segmentation: provides hassle-free traffic segmentation and stickiness without degrading performance. This is often beneficial for A/B and multivariate testing.
Cloud Marketing (Beta): if you are MediaMath customer, allows you to add JavaScript tags to your site’s pages that can communicate with MediaMath without requiring a third-party call on every page.
Cloud Marketing Plus (Beta): if you are MediaMath customer, allows you to add JavaScript tags to your site’s pages that can communicate with MediaMath and its partners without requiring a third-party call on every page.
Edge Redirector: helps you more efficiently manage large numbers of redirects. By executing redirects at the Akamai Edge, you can reduce round trips to the origin and offload hits from your origin infrastructure.
Forward Rewrite: helps you create, based on in-bound request information, human-readable and search engine optimization-friendly (SEO-friendly) URLs for dynamically-generated pages.
Input Validation: helps protect your business by confirming that the values submitted into a web application are well-formed and comply with your custom policy. This Cloudlet also provides the ability to limit the number of valid form submissions and invalid attempts per user.
Phased Release: provides, at the edge, a mechanism to define a percentage of your visitors and direct them to a different origin while maintaining visitor stickiness.
Request Control: allows you to provide conditional access to your website or application by defining and managing whitelists and blacklists based on a number of match criteria, including the IP address and geography associated with incoming requests.
Visitor Prioritization: helps maintain business continuity for your dynamic application through the use of a waiting room page in high-demand situations.
IMPORTANT: This API does not support the Image Converter Cloudlet. Use the Property Manager API to enable the Image Converter behavior.
See Akamai’s Cloudlets page for additional information about the Cloudlets that are available today.
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. We want to hear from you!
NOTE: The maximum body size for Cloudlets POST requests is 5242880 bytes.
Concepts
Cloudlets terminology
When working with Cloudlets, you need to be familiar with the following terms:
Policies: For each Cloudlet instance on your contract, there can be any number of policies. A single policy is associated with a single property configuration. Policies are versioned. Within a policy version you define the rules that determine when the Cloudlet executes. Each policy is assigned a unique ID (
policyId
).Properties: A property configuration includes all the rules for how to process end-user requests for either a specific web asset or a set of assets. For more information about properties, see the Property Manager API.
Version: A specific revision of a given policy (
policyId
). Version numbers start at 1 and increment as new versions are created for a policy. You may want to create a new version of a policy to support a different business requirement, or to test new functionality. When you activate a Cloudlet, you are activating a specific version of a Cloudlet policy.Groups: Within an account, there is a hierarchy of groups that control access to both properties and Cloudlets policies. If your Akamai username is not associated with the group (
gid
orgroupId
) being used with this API, then the request fails. In addition, you can only associate a Cloudlet policy with a property that is in a compatible group, which can either be the same group, or be an ancestor of the policy’s group.Conditional Origins: A type of origin server that you can forward Cloudlets requests to. Conditional Origins are available for the following Cloudlets: Application Load Balancer, Audience Segmentation, Forward Rewrite, and Phased Release. The base rules for all Cloudlets Origins are set up in the Property Manager API. For Application Load Balancer, you use the Conditional Origin operations to set up and maintain load balancing configurations. For the other Cloudlets that support Conditional Origins, use the Property Association operations to view information about which Conditional Origins are associated with a particular Cloudlets policy version.
About group IDs
When using this API, your level of access depends on the groups your
Akamai Control Center username is
associated with. If your username is not associated with the group ID
(gid
or groupId
) you selected, then the request fails.
To understand groups, you need to understand how accounts work at Akamai. Akamai customers access all their services using an account key. While administrators may have access to more than one account, in general they provision all their web assets under a single account. Customers typically set up groups that correspond to their firm’s own organizational hierarchy.
When using any of the GET operations available for this API, you may
include the gid
in the query parameter to associate the appropriate
group with the request.
NOTE: You can change group-level information by changing role assignments in the User Admin API, or by either creating or deleting properties in the Property Manager API (PAPI).
Cloudlets API workflow
The following is the basic workflow you need to follow when creating a new Cloudlet policy. For detailed information about the operations, see the Resources section. For information about the available properties, see the Data and Matches sections.
If you are using Conditional Origins or are setting up the Application Load Balancer Cloudlet, see Cloudlets API Workflow for Conditional Origins. Application Load Balancer always uses Cloudlets Origins.
Run a GET request on the
/cloudlets/api/v2/cloudlet-info
endpoint to retrieve the ID (cloudletId
) for the Cloudlet you are working with. You need thecloudletId
when creating a new policy.Run a GET request on the
/cloudlets/api/v2/group-info
endpoint to retrieve information about which Cloudlets are associated with the groups you have edit privileges for. You will need the group IDs (groupId
) returned when creating a Cloudlet policy.Using the
/cloudlets/api/v2/policies
endpoint, run a POST to create a Cloudlet policy using thecloudletId
andgroupId
you retrieved from the previous steps. The policy created is versionHowever, this new version does not have a description and does not include match rules (
matchRules
) attributes.NOTE: You have the option of using query parameters to clone an existing policy.
Update version 1 of the new policy by running a PUT request on the
/cloudlets/api/v2/policies/{policyId}/versions/{version}
endpoint that includes a version description and match rules. ThepolicyId
is returned in the response when the Cloudlet policy is created.If you need to review the current property associations for the policy version before activating, run a GET request on the
/cloudlets/api/v2/policies/{policyId}/properties
endpoint.NOTE: This operation also returns information about any Conditional Origins configured on an associated property. If you are using a Cloudlet that supports Conditional Origins, you may want to verify that the information returned about these origins is accurate.
Activate the policy by running a POST request to the
/cloudlets/api/v2/policies/{policyId}/versions/{version}/activations
endpoint.Using the Property Manager API (PAPI) set up the behavior for each Cloudlet you are configuring:
Using PAPI, activate the property version that includes your Cloudlets behavior changes.
Cloudlets API workflow for conditional origins
The following is the workflow you need to follow when creating a new Cloudlet policy that uses Conditional Origins. For detailed information about the operations, see the Resources section. For information about the available properties, see the Data and Matches sections.
Using the Property Manager API (PAPI), set up the rules for any Cloudlets Origins that will support the Cloudlets policy.
Run a GET request on the
/cloudlets/api/v2/cloudlet-info
endpoint to retrieve the ID (cloudletId
) for the Cloudlet you are working with. You need thecloudletId
when creating a new policy.Run a GET request on the
/cloudlets/api/v2/group-info
endpoint to retrieve information about which Cloudlets are associated with the groups you have edit privileges for. You will need the group IDs (groupId
) returned when creating a Cloudlet policy.Using the
/cloudlets/api/v2/policies
endpoint, run a POST to create a Cloudlet policy using thecloudletId
andgroupId
you retrieved from the previous steps. The policy created is versionHowever, this new version does not have a description and does not include match rules (
matchRules
) attributes.NOTE: You have the option of using query parameters to clone an existing policy.
Update version 1 of the new policy by running a PUT request on the
/cloudlets/api/v2/policies/{policyId}/versions/{version}
endpoint that includes a version description and match rules. ThepolicyId
is returned in the response when the Cloudlet policy is created.If you are setting up a load balancing configuration for Application Load Balancer complete the following tasks:
Make a POST request to
/cloudlets/api/v2/origins
.Make a POST request to
/cloudlets/api/v2/origins/{originId}/versions
.
If you need to review the current property associations for the policy version before activating, run a GET request on the
/cloudlets/api/v2/policies/{policyId}/properties
endpoint.NOTE: This operation also returns information about any Conditional Origins configured on an associated property.
Using the Property Manager API (PAPI), set up the behavior for each Cloudlet you are configuring:
Using PAPI, activate the property version that includes your Cloudlets behavior changes.
If you are setting up a load balancing configuration for Application Load Balancer, make a POST request to
/cloudlets/api/v2/origins/{originId}/activations
to activate the load balancing version.Activate the policy by executing a POST request to the
/cloudlets/api/v2/policies/{policyId}/versions/{version}/activations
endpoint.
Interactions with Property Manager
Policy activation
During policy activation you can associate a Cloudlets policy version with one or more properties that are within a compatible group.
You can do this by setting the additionalPropertyNames
member in the
activation request to the
/cloudlets/api/v2/policies/{policyId}/versions/{version}/activations
endpoint.
If you want to associate a property with a specific Cloudlets policy, use the Property Manager API to add the name of the Cloudlets policy to the Cloudlet behavior within the property.
Conditional origins
A Conditional Origin is a type of origin server that you can forward Cloudlets requests to. You can use Conditional Origins with the following Cloudlets: Application Load Balancer, Audience Segmentation, Forward Rewrite, and Phased Release. The base rules for all Conditional Origins are set up in the Property Manager API. You do not need to activate the property version containing the Conditional Origins in order to use the Conditional Origins with the Cloudlets API. You only need to make the changes and issue a PUT request to save your changes.
Activation (going live)
The various activation operations allow you to activate a policy version on the selected network, or retrieve current or historical activation information for a Cloudlet policy.
To use the activation operations, you need to know the version of the policy you want to activate or view. The following are the activation statuses that are returned with the response:
inactive: The policy version has not been activated. No active property versions reference this policy.
active: The policy version is currently active (published) and its associated property version is also active.
deactivated: The policy version was previously activated but it has been superseded by a more recent activation of another policy version.
pending: The policy version is proceeding through the activation workflow.
failed: The policy version activation workflow has failed.
NOTE: If a failure occurs and you are not sure of the cause, be sure to include the
statusDetail
and the status code from the response in any tickets you file.
You can activate a policy version on a network if it is associated
with a property and has a status of either inactive
, failed
, or
deactivated
. Policies with a pending
status cannot be reactivated.
NOTE: Policies with no active versions do not contain activation information in the response body.
Activate a policy version
You can activate a policy version with a POST operation against the
../policies/{nnn}/activations
endpoint, if you
include the network
and policyVersion
attributes. In this case the
policy is identified using the URI pathname.
If you include the network
attribute in the request body, you can
also activate a policy version by issuing a POST to the
../policies/{nnn}/versions/{nnn}/activations
endpoint.
In addition, if the property version that references the Cloudlet policy is activated, an activation record is created.
NOTE: The property activation status is either
active
orinactive
.
See the Resources section for examples of activation requests and responses.
Activation times
The following are the average activation times for each Cloudlet:
Cloudlet | Average Activation Time |
---|---|
Application Load Balancer | 30 seconds to 1 minute |
API Prioritization | 30 seconds to 1 minute |
Audience Segmentation | 30 to 45 minutes |
Cloud Marketing | 30 seconds to 1 minute |
Cloud Marketing Plus | 30 seconds to 1 minute |
Edge Redirector | 30 to 45 minutes |
Forward Rewrite | 30 to 45 minutes |
Input Validation | 30 to 45 minutes |
Phased Release | 30 seconds to 1 minute |
Request Control | 30 seconds to 1 minute |
Visitor Prioritization | 30 seconds to 1 minute |
NetStorage activation considerations
For NetStorage activations, Cloudlet policy activations either succeed
or fail immediately. Once an activation is successful, the status
changes to active
, and the status of the previously active policy
version changes to deactivated
.
If an activation failure occurs, the status is still inactive
, and
the previously active policy version continues to be active
. The
response includes the reason for the failure.
Test the activated policy
When activating a new policy, you should first deploy it to the staging network and then perform testing. Once testing is successfully completed, repeat the activation operations on the Production network to deploy your new policy.
Note that the associated property also has to be activated before you can begin testing. See the Activations section of the Property Manager API for more information.
Resources
The Cloudlets v2 API allows you to create and view Cloudlet policies and policy versions. Use this API to activate a Cloudlet policy version on either the staging or production network, delete a Cloudlet policy or a policy version, or view group-level information about a particular Cloudlet.
Operations listed under Load Balancing Configurations only apply
to the Application Load Balancer Cloudlet. The
/cloudlets/api/v2/conditional-origins?{policyId}
endpoint that was
previously used for Conditional Origins has been deprecated. The
Property Associations operations return information about
Conditional Origins.
API summary
Operation | Method | Endpoint |
---|---|---|
Cloudlets | ||
List Cloudlets | GET | /cloudlets/ |
Get a Cloudlet | GET | /cloudlets/ |
Group-Level Cloudlets | ||
List Groups | GET | /cloudlets/ |
Get a Group | GET | /cloudlets/ |
Policies | ||
List Policies | GET | /cloudlets/ |
Create a Policy | POST | /cloudlets/ |
Get a Policy | GET | /cloudlets/ |
Update a Policy | PUT | /cloudlets/ |
Remove a Policy | DELETE | /cloudlets/ |
Policy Versions | ||
List Policy Versions | GET | /cloudlets/ |
Create a New Policy Version | POST | /cloudlets/ |
Get a Policy Version | GET | /cloudlets/ |
Update a Policy Version | PUT | /cloudlets/ |
Remove a Policy Version | DELETE | /cloudlets/ |
Add a Version Rule | POST | /cloudlets/ |
Get a Version Rule | GET | /cloudlets/ |
Update a Version Rule | PUT | /cloudlets/ |
Property Associations | ||
List Associated Properties | GET | /cloudlets/ |
Get Associated Properties for a Policy | GET | /cloudlets/ |
Load Balancing Configurations for Application Load Balancer | ||
List Conditional Origins | GET | /cloudlets/ |
Get a Conditional Origin | GET | /cloudlets/ |
Create a Load Balancing Configuration | POST | /cloudlets/ |
Update a Load Balancing Configuration | PUT | /cloudlets/ |
List Load Balancing Versions | GET | /cloudlets/ |
Create a Load Balancing Version | POST | /cloudlets/ |
Get a Load Balancing Version | GET | /cloudlets/ |
Update a Load Balancing Version | PUT | /cloudlets/ |
Load Balancing Version Activations | ||
List Current Load Balancing Activations | GET | /cloudlets/ |
List Activations for a Load Balancing Configuration | GET | /cloudlets/ |
Activate a Load Balancing Version | POST | /cloudlets/ |
Policy Activations | ||
List Policy Activations | GET | /cloudlets/ |
Activate a Policy Version | POST | /cloudlets/ |
Schemas | ||
Get a Schema | GET | /cloudlets/ |
List Schemas per Cloudlet | GET | /cloudlets/ |
List cloudlets
Returns name, code, and ID (cloudletId
) information for all
available Cloudlets. You need the cloudletId
when creating a new
Policy.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
gid |
Number | 11754 |
For GET operations, returns data about the available types of Cloudlets the user can access for the specified group ID. |
Status 200
application/json
Response Body:
[
{
"serviceVersion": null,
"apiVersion": "2.0",
"location": "/cloudlets/api/v2/cloudlet-info/3",
"cloudletId": 3,
"cloudletCode": "FR",
"cloudletName": "FORWARDREWRITE"
},
{
"serviceVersion": null,
"apiVersion": "2.0",
"location": "/cloudlets/api/v2/cloudlet-info/0",
"cloudletId": 0,
"cloudletCode": "ER",
"cloudletName": "EDGEREDIRECTOR"
}
]
Get a cloudlet
Returns name, code, and ID information for a specific type of
Cloudlet. You need the cloudletId
when creating a new Policy.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Optional | |||
cloudletId |
Number | 1001 |
For GET operations, returns only policies for this particular cloudletId . |
Status 200
application/json
Response Body:
{
"serviceVersion": null,
"apiVersion": "2.0",
"location": "/cloudlets/api/v2/cloudlet-info/0",
"cloudletId": 0,
"cloudletCode": "ER",
"cloudletName": "EDGEREDIRECTOR"
}
Run the List Cloudlets operation.
Store the
cloudletId
from the appropriate object within the listing.Make a GET request to
/cloudlets/api/v2/cloudlet-info{?gid}
.
List groups
Returns information about the Cloudlet types associated with the groups you have edit privileges for.
GET /cloudlets/
Status 200
application/json
Response Body:
[
{
"location": "/cloudlets/api/v2/group-info/1234",
"serviceVersion": null,
"apiVersion": "2.0",
"groupId": 1234,
"groupName": "Master Group Name",
"parentId": 0,
"capabilities": [
{
"cloudletId": 3,
"cloudletCode": "FR",
"capabilities": [
"View",
"Edit",
"Activate"
]
},
{
"cloudletId": 0,
"cloudletCode": "ER",
"capabilities": [
"View",
"Edit",
"Activate",
"AdvancedEdit"
]
}
],
"properties": null
},
{
"location": "/cloudlets/api/v2/group-info/5678",
"serviceVersion": null,
"apiVersion": "2.0",
"groupId": 5678,
"groupName": "Subgroup 1",
"parentId": 1234,
"capabilities": [
{
"cloudletId": 0,
"cloudletCode": "ER",
"capabilities": [
"View",
"Edit",
"Activate"
]
}
],
"properties": null
}
]
Get a group
Returns information about the Cloudlet types associated with the selected group. For results to display, you must have edit privileges for one or more Cloudlet types within the group.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
groupId |
Number | 11754 |
For GET operations, returns only policies associated with the group ID entered. Enter 0 to get policies in all groups. |
Status 200
application/json
Response Body:
[
{
"location": "/cloudlets/api/v2/group-info/1234",
"serviceVersion": null,
"apiVersion": "2.0",
"groupId": 1234,
"groupName": "Master Group Name",
"parentId": 0,
"capabilities": [
{
"cloudletId": 3,
"cloudletCode": "FR",
"capabilities": [
"View",
"Edit",
"Activate"
]
},
{
"cloudletId": 0,
"cloudletCode": "ER",
"capabilities": [
"View",
"Edit",
"Activate",
"AdvancedEdit"
]
}
],
"properties": null
}
]
Run the List Groups operation.
Store the
groupId
from the appropriate object within the listing.Make a GET request to
/cloudlets/api/v2/group-info/{groupId}
.
List policies
Returns information for all available policies.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Optional | |||
clonePolicyId |
Number | 11754 |
If cloning an existing policy, this parameter is the ID of the policy (policyId ) you want to clone. If there are attributes that you do not want propagated from the source policy, you must provide the new values in the request. |
cloudletId |
Number | 1001 |
For GET operations, returns only policies for this particular cloudletId . |
gid |
Number | 11754 |
For GET operations, returns only policies associated with the group ID (gid ) entered. |
includeDeleted |
Boolean | false |
For GET operations, includes deleted policies in the results. |
version |
Number | 10 |
For POST operations, indicates the version of the existing policy to use for the new policy. If not specified, the latest version of the existing policy is copied. |
offset |
Number | 25 |
When requesting pages of data, offset is the record after which to start. Use with pageSize to page through data. Ex: offset=25&pageSize=25 will start at record 26 and display 25 records. |
pageSize |
Number | 10 |
The number of records to return. Use with offset to page through data. |
Status 200
application/json
Response Body:
[
{
"location": "/cloudlets/api/v2/policies/1001",
"serviceVersion": null,
"apiVersion": "2.0",
"policyId": 1001,
"cloudletId": 99,
"cloudletCode": "CC",
"groupId": 1234,
"name": "CookieCutter",
"description": "Custom cookie cutter",
"propertyName": "www.example.org",
"createdBy": "sjones",
"createDate": 1400535431324,
"lastModifiedBy": "sjones",
"lastModifiedDate": 1441829042000,
"activations": [
{
"serviceVersion": null,
"apiVersion": "2.0",
"network": "prod",
"policyInfo": {
"policyId": 1001,
"name": "CookieCutter",
"version": 2,
"status": "INACTIVE",
"statusDetail": "waiting to complete tests in test environment",
"detailCode": 0,
"activatedBy": "jsmith",
"activationDate": 1441829042000
},
"propertyInfo": {
"name": "www.example.org",
"version": 2,
"groupId": 1234,
"status": "INACTIVE",
"activatedBy": "sjones",
"activationDate": 1441137842000
}
},
{
"serviceVersion": null,
"apiVersion": "2.0",
"network": "test",
"policyInfo": {
"policyId": 1001,
"name": "CookieCutter",
"version": 22,
"status": "ACTIVE",
"statusDetail": "testing",
"detailCode": 0,
"activatedBy": "jsmith",
"activationDate": 1400535431000
},
"propertyInfo": {
"name": "www.example.org",
"version": 22,
"groupId": 1234,
"status": "ACTIVE",
"activatedBy": "jsmith",
"activationDate": 1441137842000
}
}
]
}
]
Create a policy
Create a new Cloudlet policy. If a policy already exists with the same policy name, you receive a 409 (Conflict) status response that contains data for the existing policy. New policies are automatically assigned version number 1.
POST /cloudlets/
Sample: /cloudlets/
Content-Type: application/json
Request Body:
{
"cloudletId": 99,
"groupId": 1234,
"name": "TestCreatePolicy1",
"description": "Testing the creation of a policy"
}
Parameter | Type | Sample | Description |
---|---|---|---|
Optional | |||
clonePolicyId |
Number | 11754 |
If cloning an existing policy, this parameter is the ID of the policy (policyId ) you want to clone. If there are attributes that you do not want propagated from the source policy, you must provide the new values in the request. |
cloudletId |
Number | 1001 |
For GET operations, returns only policies for this particular cloudletId . |
gid |
Number | 11754 |
For GET operations, returns only policies associated with the group ID (gid ) entered. |
includeDeleted |
Boolean | false |
For GET operations, includes deleted policies in the results. |
version |
Number | 10 |
For POST operations, indicates the version of the existing policy to use for the new policy. If not specified, the latest version of the existing policy is copied. |
Status 201
application/json
Response Body:
{
"location": "/cloudlets/api/v2/policies/1002",
"serviceVersion": null,
"apiVersion": "2.0",
"policyId": 1002,
"cloudletId": 99,
"cloudletCode": "CC",
"groupId": 1234,
"name": "CreatePolicy1",
"description": "Creating a policy",
"deleted": false,
"propertyName": null,
"createdBy": "sjones",
"createDate": 1428957069841,
"lastModifiedBy": "jsmith",
"lastModifiedDate": 1428957070000,
"activations": []
}
Run the List Cloudlets operation and store the
cloudletId
.Run the List Groups operation and store the
groupId
.Create a JSON file with the following required members:
cloudletId
,groupId
,name
. See the Policy for a listing of all members.Make a POST request to
/cloudlets/api/v2/policies
, specifying the JSON in the body of the request.
Get a policy
Returns information about a specific Cloudlets policy.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
policyId |
Number | 11754 |
The ID of the policy. |
Status 200
application/json
Response Body:
{
"location": "/cloudlets/api/v2/policies/1001",
"serviceVersion": null,
"apiVersion": "2.0",
"policyId": 1001,
"cloudletId": 99,
"cloudletCode": "CC",
"groupId": 1234,
"name": "CookieCutter",
"description": "Custom cookie cutter",
"propertyName": "www.example.org",
"createdBy": "jsmith",
"createDate": 1428957070000,
"lastModifiedBy": "sjones",
"lastModifiedDate": 1441829042000,
"activations": [
{
"serviceVersion": null,
"apiVersion": "2.0",
"network": "prod",
"policyInfo": {
"policyId": 1001,
"name": "CookieCutter",
"version": 2,
"status": "INACTIVE",
"statusDetail": "waiting to complete tests in test environment",
"detailCode": 0,
"activatedBy": "jsmith",
"activationDate": 1433901173000
},
"propertyInfo": {
"name": "www.example.org",
"version": 2,
"groupId": 1234,
"status": "INACTIVE",
"activatedBy": "sjones",
"activationDate": 1441829042000
}
},
{
"serviceVersion": null,
"apiVersion": "2.0",
"network": "test",
"policyInfo": {
"policyId": 1001,
"name": "CookieCutter",
"version": 22,
"status": "ACTIVE",
"statusDetail": "testing",
"detailCode": 0,
"activatedBy": "jsmith",
"activationDate": 1433901173000
},
"propertyInfo": {
"name": "www.example.org",
"version": 22,
"groupId": 1234,
"status": "ACTIVE",
"activatedBy": "jsmith",
"activationDate": 1441915442000
}
}
]
}
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Make a GET request to
/cloudlets/api/v2/policies/{policyId}
.
Update a policy
Update attributes of an existing policy.
When updating a policy, note the following:
If you change the policy name, the new name must be unique.
Changes to policy names are not allowed if the policy is currently associated with one or more properties.
If a policy already exists with the same policy name, you receive a 409 (Conflict) status. The response contains data for the existing policy.
If you are updating a previously deleted policy by setting its
deleted
attribute tofalse
, the operation fails if there is a name conflict with another policy.The
cloudletId
andgroupId
are not required as they are for a POST request to this endpoint.
PUT /cloudlets/
Sample: /cloudlets/
Content-Type: application/json
Request Body:
{
"description": "Testing the update of a policy",
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
policyId |
Number | 11754 |
The ID of the policy. |
Status 200
application/json
Response Body:
{
"location": "/cloudlets/api/v2/policies/1002",
"serviceVersion": null,
"apiVersion": "2.0",
"policyId": 1002,
"cloudletId": 99,
"cloudletCode": "CC",
"groupId": 1234,
"name": "CookieCutter",
"description": "Testing the update of a policy",
"deleted": false,
"propertyName": null,
"createdBy": "sjones",
"createDate": 1428957070000,
"lastModifiedBy": "jsmith",
"lastModifiedDate": 1431549070000,
"activations": []
}
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Run the Get a Policy operation for the selected
policyId
.Modify the JSON file returned with the desired updates to the policy.
Make a PUT request to
/cloudlets/api/v2/policies/{policyId}
, specifying the modified JSON in the body of the request.
Remove a policy
When you delete a policy, you can reuse the deleted policy’s name in
another policy. Deleting a policy sets its deleted
attribute to
true
, which hides the policy from normal GET requests and makes the
policy name available for use on another policy. There are also the
following considerations when you delete a policy:
In Property Manager, if you try to reactivate an old property version that references the deleted policy, the operation fails.
A policy cannot be deleted if it is currently included in the behavior set of some active property version.
NOTE: If the GET request specifies the
includeDeleted
parameter, the response includes deleted policies.
You can also undelete a policy by setting its deleted
attribute to
false
with a PUT request against
policies/{nnn}
. However, if the policy name would
conflict with the name of another policy that was created since the
current policy was deleted, the operation fails. If the old name is no
longer available, you can both undelete a policy and change its name
in a single PUT request.
NOTE: A successful DELETE operation returns a status code of 204 (No Content).
DELETE /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
policyId |
Number | 11754 |
The ID of the policy. |
Status 204
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Make a DELETE request to
/cloudlets/api/v2/policies/{policyId}
.
List policy versions
Returns information about all versions of a policy.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
policyId |
Number | 11754 |
The ID of the policy. |
Optional | |||
cloneVersion |
Number | 10 |
If cloning an existing policy version, this parameter value is the number of the policy version you want to clone. If there are attributes that you do not want propagated from the source policy version, you must provide the new values in the request. |
includeRules |
Boolean | false |
Includes the match rules for all policy versions in the results. Defaults to false . |
matchRuleFormat |
String | 1.0 |
Returns the matchRuleFormat version string, which shows the version of the Cloudlet-specific matchRules used. Defaults to 1.0 . |
offset |
Number | 25 |
When requesting pages of data, offset is the record after which to start. Use with pageSize to page through data. Ex: offset=25&pageSize=25 will start at record 26 and display 25 records. |
pageSize |
Number | 10 |
The number of records to return. Use with offset to page through data. |
Status 200
application/json
Response Body:
[
{
"revisionId": 11868,
"policyId": 1001,
"version": 1,
"description": "test",
"createdBy": "jsmith",
"createDate": 1427133615439,
"lastModifiedBy": "sjones",
"lastModifiedDate": 1427133651975,
"activations": [],
"matchRules": [],
"rulesLocked": false
},
{
"revisionId": 11870,
"policyId": 1001,
"version": 2,
"description": "v2",
"createdBy": "jsmith",
"createDate": 1427133784903,
"lastModifiedBy": "sjones",
"lastModifiedDate": 1427133805767,
"activations": [],
"matchRules": [],
"rulesLocked": false
}
]
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Make a GET request to
/cloudlets/api/v2/policies/{policyId}/versions
to return all versions of the policy.
Create a new policy version
Create a new policy version, where the version number increments from the highest existing version. With this operation you can change any modifiable policy or version attributes.
The newly created policy version number is included in the response
and is one number greater than the previously highest version. The
default value for description
is an empty string and there are no
matchRules
. However, if you use the cloneVersion
query parameter
with the POST request, then the default values for these attributes
are taken from the latest version.
POST /cloudlets/
Sample: /cloudlets/
Content-Type: application/json
Request Body:
{
"description": "Testing the cloning of a policy",
"matchRuleFormat": "1.0",
"matchRules": []
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
policyId |
Number | 11754 |
The ID of the policy. |
Optional | |||
cloneVersion |
Number | 10 |
If cloning an existing policy version, this parameter value is the number of the policy version you want to clone. If there are attributes that you do not want propagated from the source policy version, you must provide the new values in the request. |
includeRules |
Boolean | false |
Includes the match rules for all policy versions in the results. Defaults to false . |
matchRuleFormat |
String | 1.0 |
Returns the matchRuleFormat version string, which shows the version of the Cloudlet-specific matchRules used. Defaults to 1.0 . |
Status 200
application/json
Response Body:
{
"revisionId": 12345,
"policyId": 1002,
"version": 2,
"description": "Cloning a policy",
"createdBy": "sjones",
"createDate": 1428957891084,
"lastModifiedBy": "jsmith",
"lastModifiedDate": 1428957891084,
"activations": [],
"matchRules": [],
"rulesLocked": false
}
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Make a POST request to
/cloudlets/api/v2/policies/{policyId}/versions
.
Get a policy version
Returns information about a specific Cloudlet policy version.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
policyId |
Number | 11754 |
The ID of the policy. |
version |
Number | 10 |
The version number of the policy. |
Optional | |||
matchRuleFormat |
String | 1.0 |
Returns the matchRuleFormat version string, which shows the version of the Cloudlet-specific matchRules used. Defaults to 1.0 . |
omitRules |
Boolean | false |
Excludes the match rules from the results. Defaults to false . |
Status 200
application/json
Response Body:
{
"revisionId": 11870,
"policyId": 1001,
"version": 2,
"description": "v2",
"createdBy": "jsmith",
"createDate": 1427133784903,
"lastModifiedBy": "sjones",
"lastModifiedDate": 1427133805767,
"activations": [],
"matchRules": [],
"rulesLocked": false
}
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Run the List Policy Versions operation.
Store the
version
from the appropriate object within the listing.Make a GET request to
/cloudlets/api/v2/policies/{policyId}/versions/{version}
.
Update a policy version
Update attributes of an existing policy version.
PUT /cloudlets/
Sample: /cloudlets/
Content-Type: application/json
Request Body:
{ "description": "v1 for Q1 Sales" }
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
policyId |
Number | 11754 |
The ID of the policy. |
version |
Number | 10 |
The version number of the policy. |
Optional | |||
matchRuleFormat |
String | 1.0 |
Returns the matchRuleFormat version string, which shows the version of the Cloudlet-specific matchRules used. Defaults to 1.0 . |
omitRules |
Boolean | false |
Excludes the match rules from the results. Defaults to false . |
Status 200
application/json
Response Body:
{
"revisionId": 11870,
"policyId": 1001,
"version": 1,
"description": "v1 for Q1 sales",
"createdBy": "sjones",
"createDate": 1427133784903,
"lastModifiedBy": "sjones",
"lastModifiedDate": 1427133805767,
"activations": [],
"matchRules": [],
"rulesLocked": false
}
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Run the List Policy Versions operation.
Store the
version
you want to update.Run the Get a Policy Version operation.
Modify the JSON file returned with any changes to match rules or version-level information. The
description
andmatchRuleFormat
members are required.Make a PUT request to
/cloudlets/api/v2/policies/{policyId}/versions/{version}
, specifying the modified JSON in the body of the request.
Remove a policy version
You have the option of removing policy versions, including those that are currently active on either the staging or production network. Once a policy version is deleted, you can still create a new policy version based on the deleted version.
Also, if you make changes to a deleted policy version, it is automatically undeleted and available for use.
When you remove a policy version, version numbers are not reallocated. For example, a policy has 15 versions, and you delete versions 14 and 15. The next version created would be 16, not 14.
A successful DELETE operation returns a status code of 204 (No Content).
DELETE /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
policyId |
Number | 11754 |
The ID of the policy. |
version |
Number | 10 |
The version number of the policy. |
Optional | |||
matchRuleFormat |
String | 1.0 |
Returns the matchRuleFormat version string, which shows the version of the Cloudlet-specific matchRules used. Defaults to 1.0 . |
omitRules |
Boolean | false |
Excludes the match rules from the results. Defaults to false . |
Status 204
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Run the List Policy Versions operation.
Store the
version
from the appropriate object within the listing.Make a DELETE request to
/cloudlets/api/v2/policies/{policyId}/versions/{version}
.
Add a version rule
Add a new rule to an existing policy version. You can only add one rule at a time.
When adding a rule, use the index
query parameter to set the
position of the new rule within in the current list of rules. If you
do not set this parameter, the new rule is added to the end of the
current rule list. For Cloudlets, the first rule listed is the first
rule evaluated.
POST /cloudlets/
Sample: /cloudlets/
Content-Type: application/json
Request Body:
{
"matches": [
{
"matchType": "range",
"objectMatchValue": {
"type": "range",
"value": [1, 25]
},
"matchOperator": "equals",
"negate": false,
"caseSensitive": false
}
],
"start": 0,
"end": 0,
"type": "asMatchRule",
"disabled": "false",
"forwardSettings": {
"originId": "originremote2",
"useIncomingQueryString": true,
"pathAndQS": "/sales/Q1/"
},
"name": "Q1Sales",
"id": null
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
policyId |
Number | 11754 |
The ID of the policy. |
version |
Number | 10 |
The version number of the policy. |
Optional | |||
index |
Number | 3 |
The order within the current list of rules where you want to add the new rule. If you do not set this parameter, the new rule is added to the end of the current rule list. For Cloudlets, the first rule listed is the first rule evaluated. |
Status 200
application/json
Response Body:
{
"location": "/cloudlets/api/v2/policies/1002/versions/2/rules/5db847a66e0566ad",
"akaRuleId": "5db847a66e0566ad",
"matches": [
{
"matchType": "range",
"objectMatchValue": {
"type": "range",
"value": [1, 25]
},
"matchOperator": "equals",
"negate": false,
"caseSensitive": false
}
],
"start": 0,
"end": 0,
"type": "asMatchRule",
"disabled": "false",
"forwardSettings": {
"originId": "originremote2",
"useIncomingQueryString": true,
"pathAndQS": "/sales/Q1/"
},
"name": "Q1Sales",
"id": null
}
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Run the List Policy Versions operation with the
includeRules
query parameter set totrue
.Store the
version
number and theakaRuleId
from the appropriate object within the listing.Create a JSON file with the new match rules.
Make a POST request to
/cloudlets/api/v2/policies/{policyId}/versions/{version}/rules
, specifying the JSON in the body of the request.
Get a version rule
Returns information about a specific rule within a policy version.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
akaRuleId |
String | 5db847a66e0566ad |
The ID of the rule within the policy version. |
policyId |
Number | 11754 |
The ID of the policy. |
version |
Number | 10 |
The version number of the policy. |
Status 200
application/json
Response Body:
{
"location": "/cloudlets/api/v2/policies/1002/versions/2/rules/5db847a66e0566ad",
"akaRuleId": "5db847a66e0566ad",
"matches": [
{
"matchType": "range",
"objectMatchValue": {
"type": "range",
"value": [1, 25]
},
"matchOperator": "equals",
"negate": false,
"caseSensitive": false
}
],
"start": 0,
"end": 0,
"type": "asMatchRule",
"disabled": "false",
"forwardSettings": {
"originId": "originremote2",
"useIncomingQueryString": true,
"pathAndQS": "/sales/Q1/"
},
"name": "Q1Sales",
"id": null
}
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Run the List Policy Versions operation with the
includeRules
query parameter set totrue
.Store the
version
number and theakaRuleId
from the appropriate object within the listing.Make a GET request to
/cloudlets/api/v2/policies/{policyId}/versions/{version}/rules/{akaRuleId}
.
Update a version rule
Updates attributes of an existing rule within a policy version.
When updating a rule, use the disabled
member to prevent the rule
from being evaluated against incoming requests.
PUT /cloudlets/
Sample: /cloudlets/
Content-Type: application/json
Request Body:
{ "disabled": "true" }
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
akaRuleId |
String | 5db847a66e0566ad |
The ID of the rule within the policy version. |
policyId |
Number | 11754 |
The ID of the policy. |
version |
Number | 10 |
The version number of the policy. |
Status 200
application/json
Response Body:
{
"location": "/cloudlets/api/v2/policies/1002/versions/2/rules/5db847a66e0566ad",
"akaRuleId": "5db847a66e0566ad",
"matches": [
{
"matchType": "range",
"objectMatchValue": {
"type": "range",
"value": [1, 25]
},
"matchOperator": "equals",
"negate": false,
"caseSensitive": false
}
],
"start": 0,
"end": 0,
"type": "asMatchRule",
"disabled": "true",
"forwardSettings": {
"originId": "originremote2",
"useIncomingQueryString": true,
"pathAndQS": "/sales/Q1/"
},
"name": "Q1Sales",
"id": null
}
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Run the List Policy Versions operation with the
includeRules
query parameter set totrue
.Store the
version
number and theakaRuleId
from the appropriate object within the listing.Create a JSON file with any changes to match rules.
Make a PUT request to
/cloudlets/api/v2/policies/{policyId}/versions/{version}/rules/{akaRuleId}
, specifying the JSON in the body of the request.
List associated properties
GET /cloudlets/
Status 200
application/json
Response Body:
{
"www.myproperty.com": {
"groupId": 40498,
"name": "www.myproperty.com",
"newestVersion": {
"activatedBy": "jsmith",
"activationDate": "2015-08-25",
"cloudletsOrigins": {
"clorigin2": {
"id": "clorigin2",
"hostname": "origin2.myproperty.com",
"checksum": "0edc0bb1be7439248a77f48e806d2531",
"type": "CUSTOMER"
},
"clorigin1": {
"id": "clorigin1",
"hostname": "origin1.myproperty.com",
"checksum": "eefa90e680a1183725cfe2a1f00307c4",
"type": "CUSTOMER"
}
},
"version": 5,
"referencedPolicies": [
"fr_policy_1"
]
},
"production": {
"activatedBy": "jsmith",
"activationDate": "2015-08-26",
"cloudletsOrigins": {
"clorigin2": {
"id": "clorigin2",
"hostname": "origin2.myproperty.com",
"checksum": "0edc0bb1be7439248a77f48e806d2531",
"type": "CUSTOMER"
},
"clorigin1": {
"id": "clorigin1",
"hostname": "origin1.myproperty.com",
"checksum": "eefa90e680a1183725cfe2a1f00307c4",
"type": "CUSTOMER"
}
},
"version": 5,
"referencedPolicies": [
"fr_policy_1"
]
},
"staging": {
"activatedBy": "sjones",
"activationDate": "2015-08-25",
"cloudletsOrigins": {
"clorigin2": {
"id": "clorigin2",
"hostname": "origin2.myproperty.com",
"checksum": "0edc0bb1be7439248a77f48e806d2531",
"type": "CUSTOMER"
},
"clorigin1": {
"id": "clorigin1",
"hostname": "origin1.myproperty.com",
"checksum": "eefa90e680a1183725cfe2a1f00307c4",
"type": "CUSTOMER"
}
},
"version": 5,
"referencedPolicies": [
"fr_policy_1"
]
}
}
}
Get associated properties for a policy
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
policyId |
Number | 11754 |
The ID of the policy. |
Status 200
application/json
Response Body:
{
"www.myproperty.com": {
"groupId": 40498,
"name": "www.myproperty.com",
"newestVersion": {
"activatedBy": "sjones",
"activationDate": "2015-08-25",
"cloudletsOrigins": {
"clorigin2": {
"id": "clorigin2",
"hostname": "origin2.myproperty.com",
"checksum": "0edc0bb1be7439248a77f48e806d2531",
"type": "CUSTOMER"
},
"clorigin1": {
"id": "clorigin1",
"hostname": "origin1.myproperty.com",
"checksum": "eefa90e680a1183725cfe2a1f00307c4",
"type": "CUSTOMER"
}
},
"version": 5,
"referencedPolicies": [
"fr_policy_1"
]
},
"production": {
"activatedBy": "jsmith",
"activationDate": "2015-08-26",
"cloudletsOrigins": {
"clorigin2": {
"id": "clorigin2",
"hostname": "origin2.myproperty.com",
"checksum": "0edc0bb1be7439248a77f48e806d2531",
"type": "CUSTOMER"
},
"clorigin1": {
"id": "clorigin1",
"hostname": "origin1.myproperty.com",
"checksum": "eefa90e680a1183725cfe2a1f00307c4",
"type": "CUSTOMER"
}
},
"version": 5,
"referencedPolicies": [
"fr_policy_1"
]
},
"staging": {
"activatedBy": "jsmith",
"activationDate": "2015-08-25",
"cloudletsOrigins": {
"clorigin2": {
"id": "clorigin2",
"hostname": "origin2.myproperty.com",
"checksum": "0edc0bb1be7439248a77f48e806d2531",
"type": "CUSTOMER"
},
"clorigin1": {
"id": "clorigin1",
"hostname": "origin1.myproperty.com",
"checksum": "eefa90e680a1183725cfe2a1f00307c4",
"type": "CUSTOMER"
}
},
"version": 5,
"referencedPolicies": [
"fr_policy_1"
]
}
}
}
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Make a GET request to
/cloudlets/api/v2/policies/{policyId}/properties
, which returns a list of associated properties for a policy
List conditional origins
For this operation, you have the option of using the type
query
parameter to narrow the number of results returned by origin type.
Options for the type
parameter include APPLICATION_LOAD_BALANCER
for Application Load Balancer origins, CUSTOMER
for standard
origins, and NETSTORAGE
for NetStorage-based origins. You can use
an APPLICATION_LOAD_BALANCER
type to create a load balancing
configuration.
NOTE: For Application Load Balancer, you can only use origins of type
CUSTOMER
for the data center origins. Origins with an origin type ofAPPLICATION_LOAD_BALANCER
can support load balancing configurations.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Optional | |||
type |
String | APPLICATION_LOAD_BALANCER |
Returns data for a specific type of origin as defined in Property Manager. Options include alb for Application Load Balancer origins, customer for standard origins, and netstorage for NetStorage-based origins. |
Status 200
application/json
Response Body:
[
{
"originId": "nsorigin1",
"hostname": "download.akamai.com/12345",
"checksum": "013c0cdefg7439248a77f48e806d2531",
"type": "NETSTORAGE"
},
{
"originId": "clorigin2",
"hostname": "origin2.myproperty.com",
"checksum": "eefa90cdefg9183725cfe2a1f00307c4",
"type": "CUSTOMER"
},
{
"originId": "alborigin1",
"checksum": "abcdefg1111hijklmn22222fff76yae2",
"description": "My super awesome ALB origin"
"type": "APPLICATION_LOAD_BALANCER"
}
]
Get a conditional origin
Run this operation to pull data about a specific Conditional Origin from the Property Manager API and into the Cloudlets API.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
originId |
String | clorigin1 |
Unique identifier for the origin. |
Status 200
application/json
Response Body:
[
{
"originId": "clorigin1",
"checksum": "abcdefg1111hijklmn22222fff76yae3",
"description": "Origin for mobile user forwarding."
"type": "APPLICATION_LOAD_BALANCER"
}
]
Run the List Conditional Origins operation.
Store the
originId
from the appropriate object within the listing.Make a GET request to
/cloudlets/api/v2/origins/{originId}
.
Create a load balancing configuration
For Application Load Balancer, run this operation to create a load balancing configuration.
This operation is only available for the APPLICATION_LOAD_BALANCER
origin type.
POST /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
originId |
String | clorigin1 |
Unique identifier for the origin. |
Status 200
application/json
Response Body:
{
"originId": "clorigin1",
"checksum": "abcdefg1111hijklmn22222fff76yae3",
"description": "Test load balancing configuration."
"type": "APPLICATION_LOAD_BALANCER"
}
Run the List Conditional Origins operation to verify that the
originId
you want to create isn’t already in use.Make a POST request to
/cloudlets/api/v2/origins/{originId}
.
Update a load balancing configuration
For Application Load Balancer, run this operation to update the description of an existing load balancing configuration.
This operation is only available for the APPLICATION_LOAD_BALANCER
origin type.
PUT /cloudlets/
Sample: /cloudlets/
Content-Type: application/json
Request Body:
{
"description": "Test load balancing configuration."
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
originId |
String | clorigin1 |
Unique identifier for the origin. |
Status 200
application/json
Response Body:
{
"originId": "clorigin1",
"checksum": "abcdefg1111hijklmn22222fff76yae3",
"description": "Test load balancing configuration."
"type": "APPLICATION_LOAD_BALANCER"
}
Run the List Conditional Origins operation.
Store the
originId
from the appropriate object within the listing.Create a JSON file with an updated entry for the
description
member.Make a PUT request to
/cloudlets/api/v2/origins/{originId}
, specifying the JSON in the body of the request.
List load balancing versions
For Application Load Balancer, run this operation to list all versions of load balancing configuration.
The response lists the versions in descending order.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
originId |
String | clorigin1 |
Unique identifier for the load balancing configuration. |
Status 200
application/json
Response Body:
[
{
"createdBy": "jjones",
"createdDate": "2016-03-08T11:42:18.690Z",
"deleted": false,
"description": "Test load balancing configuration.",
"immutable": false,
"lastModifiedBy": "ejnovak",
"lastModifiedDate": "2016-06-02T00:40:02.237Z",
"originId": "clorigin1",
"version": 2
},
{
"createdBy": "jjones",
"createdDate": "2016-02-08T11:42:18.690Z",
"deleted": false,
"description": "Production load balancing configuration.",
"immutable": false,
"lastModifiedBy": "ejnovak",
"lastModifiedDate": "2016-05-02T00:40:02.237Z",
"originId": "clorigin1",
"version": 1
}
]
Run the List Conditional Origins operation.
Store the
originId
from the appropriate object within the listing.Make a GET request to
/cloudlets/api/v2/origins/{originId}/versions
.
Create a load balancing version
You can create multiple versions of the load balancing configuration. By versioning these settings, you can test new configurations, or manage changes to the data centers supporting Application Load Balancer.
Only Conditional Origins with an originType
of
APPLICATION_LOAD_BALANCER
can support load balancing configurations.
The liveness test for Application Load Balancer uses a basic HTTP poll.
POST /cloudlets/
Sample: /cloudlets/
Content-Type: application/json
Request Body:
{
"balancingType": "WEIGHTED",
"dataCenters": [
{
"cloudService": false,
"livenessHosts": [
"clorigin3.www.example.com",
],
"latitude": 102.78108,
"longitude": -116.07064,
"continent": "NA",
"country": "US",
"originId": "clorigin3",
"percent": 100.0
}
],
"deleted": false,
"description": "Test load balancing configuration.",
"immutable": false,
"livenessSettings": {
"hostHeader": "clorigin3.www.example.com",
"interval": 25,
"path": "/status",
"port": 443,
"protocol": "HTTPS",
"status3xxFailure": false,
"status4xxFailure": true,
"status5xxFailure": false,
"timeout": 30
},
"originId": "clorigin3",
"version": 4
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
originId |
String | clorigin1 |
Unique identifier for the load balancing configuration. |
Status 201
application/json
Response Body:
{
"balancingType": "WEIGHTED",
"createdBy": "jjones",
"createdDate": "2015-10-08T11:42:18.690Z",
"dataCenters": [
{
"cloudService": false,
"livenessHosts": [
"clorigin3.www.example.com",
],
"latitude": 102.78108,
"longitude": -116.07064,
"continent": "NA",
"country": "US",
"originId": "clorigin3",
"percent": 100.0
}
],
"deleted": false,
"description": "Test load balancing configuration."
"immutable": false,
"lastModifiedBy": "ejnovak",
"lastModifiedDate": "2016-05-02T00:40:02.237Z",
"livenessSettings": {
"hostHeader": "clorigin3.www.example.com",
"interval": 25,
"path": "/status",
"port": 443,
"protocol": "HTTPS",
"status3xxFailure": false,
"status4xxFailure": true,
"status5xxFailure": false,
"timeout": 30
},
"originId": "clorigin3",
"version": 4
}
Run the List Conditional Origins operation.
Store the
originId
from the appropriate object within the listing.Create a JSON file with the following required members:
cloudletId
,originId
,name
. See the Cloudlets Origin members for a listing of all members.Make a POST request to
/cloudlets/api/v2/origins/{originId}/versions
, specifying the JSON in the body of the request.
Get a load balancing version
For this operation, you have the option of using the validate
query
parameter. When set to true
, this parameter verifies whether the
settings for the selected originId
and version
are valid. The
default setting for this parameter is false
.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
originId |
String | clorigin1 |
Unique identifier for the load balancing configuration. |
version |
Number | 1 |
The origin version. |
Optional | |||
validate |
Boolean | false |
For GET operations, verifies that the current settings for the selected originId and version are valid. |
Status 200
application/json
Response Body:
{
"balancingType": "WEIGHTED",
"createdBy": "jjones",
"createdDate": "2015-10-08T11:42:18.690Z",
"dataCenters": [
{
"cloudService": false,
"livenessHosts": [
"clorigin3.www.example.com",
],
"latitude": 102.78108,
"longitude": -116.07064,
"continent": "NA",
"country": "US",
"originId": "clorigin3",
"percent": 100.0
}
],
"deleted": false,
"description": "Conditional Origin for ALB rollout.",
"immutable": false,
"lastModifiedBy": "ejnovak",
"lastModifiedDate": "2016-05-02T00:40:02.237Z",
"livenessSettings": {
"hostHeader": "clorigin3.www.example.com",
"interval": 25,
"path": "/status",
"port": 443,
"protocol": "HTTPS",
"status3xxFailure": false,
"status4xxFailure": true,
"status5xxFailure": false,
"timeout": 30
},
"originId": "clorigin1",
"version": 4
}
Run the List Conditional Origins operation.
Store the
originId
from the appropriate object within the listing. The object should also have anoriginType
ofAPPLICATION_LOAD_BALANCER
.Run the List Conditional Origin Versions operation.
Store the
version
from the appropriate object within the listing.Make a GET request to
/cloudlets/api/v2/origins/{originId}/versions/{version}
.
Update a load balancing version
You cannot edit a load balancing configuration version that has ever been activated.
PUT /cloudlets/
Sample: /cloudlets/
Content-Type: application/json
Request Body:
{
"balancingType": "WEIGHTED",
"dataCenters": [
{
"cloudService": false,
"latitude": 102.78108,
"longitude": -116.07064,
"continent": "NA",
"country": "US",
"originId": "clorigin3",
"percent": 100.0
}
],
"deleted": false,
"description": "Conditional Origin for ALB rollout.",
"livenessSettings": {
"path": "/status",
"port": 443,
"protocol": "HTTPS",
"status3xxFailure": false,
"status4xxFailure": true,
"status5xxFailure": false
},
"originId": "clorigin1",
"version": 4
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
originId |
String | clorigin1 |
Unique identifier for the load balancing configuration. |
version |
Number | 1 |
The origin version. |
Optional | |||
validate |
Boolean | false |
For GET operations, verifies that the current settings for the selected originId and version are valid. |
Status 200
application/json
Response Body:
{
"balancingType": "WEIGHTED",
"createdBy": "jjones",
"createdDate": "2015-10-08T11:42:18.690Z",
"dataCenters": [
{
"cloudService": false,
"livenessHosts": [
"clorigin3.www.example.com",
],
"latitude": 102.78108,
"longitude": -116.07064,
"continent": "NA",
"country": "US",
"originId": "clorigin3",
"percent": 100.0
}
],
"deleted": false,
"description": "Test load balancing configuration.",
"immutable": false,
"lastModifiedBy": "ejnovak",
"lastModifiedDate": "2016-05-02T00:40:02.237Z",
"livenessSettings": {
"hostHeader": "clorigin3.www.example.com",
"interval": 25,
"path": "/status",
"port": 443,
"protocol": "HTTPS",
"status3xxFailure": false,
"status4xxFailure": true,
"status5xxFailure": false,
"timeout": 30
},
"originId": "clorigin1",
"version": 4
}
Run the List Conditional Origins operation.
Store the
originId
from the appropriate object within the listing. The object should also have anoriginType
ofAPPLICATION_LOAD_BALANCER
.Run the List Conditional Origin Versions operation.
Store the
version
from the appropriate object within the listing.Run the Get a Conditional Origin Version operation.
Create a JSON file with any changes to the Conditional Origin members.
Make a PUT request to
/cloudlets/api/v2/origins/{originId}/versions/{version}
, specifying the JSON in the body of the request.
List current load balancing activations
GET /cloudlets/
Status 200
application/json
Response Body:
{
"clorigin1": {
"PRODUCTION": {
"activatedBy": "jjones",
"activatedDate": "2016-04-07T18:41:34.251Z",
"network": "PRODUCTION",
"originId": "clorigin1",
"status": "active",
"version": 1
},
"STAGING": {
"activatedBy": "ejnovak",
"activatedDate": "2016-05-30T18:41:34.251Z",
"network": "PRODUCTION",
"originId": "clorigin1",
"status": "active",
"version": 2
}
},
"clorigin2": {
"STAGING": {
"activatedBy": "gzhang",
"activatedDate": "2016-02-03T18:41:34.391Z",
"network": "STAGING",
"originId": "clorigin2",
"status": "active",
"version": 1
}
}
}
List activations for a load balancing configuration
The response lists the activations by the activatedDate
with the
most recent listed first.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
originId |
String | clorigin1 |
Unique identifier for the load balancing configuration. |
Status 200
application/json
Response Body:
[
{
"activatedBy": "jjones",
"activatedDate": "2016-05-03T18:41:34.251Z",
"network": "PRODUCTION",
"originId": "clorigin1",
"status": "active",
"version": 1
},
{
"activatedBy": "ejnovak",
"activatedDate": "2016-04-07T18:41:34.461Z",
"network": "STAGING",
"originId": "clorigin1",
"status": "active",
"version": 2
}
]
Run the List Conditional Origins operation.
Store the
originId
from the appropriate object within the listing. The object should also have anoriginType
ofAPPLICATION_LOAD_BALANCER
.Make a GET request to
/cloudlets/api/v2/origins/{originId}/activations
.
Activate a load balancing version
POST /cloudlets/
Sample: /cloudlets/
Content-Type: application/json
Request Body:
{
"network": "STAGING",
"dryrun": false,
"version": 1
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
originId |
String | clorigin1 |
Unique identifier for the load balancing configuration. |
Status 200
application/json
Response Body:
[
{
"activatedBy": "jjones",
"activatedDate": "2016-04-07T18:41:34.251Z",
"network": "PRODUCTION",
"originId": "clorigin1",
"status": "active",
"dryrun": false,
"version": 1
}
]
Run the List Conditional Origins operation.
Store the
originId
from the appropriate object within the listing. The object should also have anoriginType
ofAPPLICATION_LOAD_BALANCER
.Create a JSON file that includes the required
version
andnetwork
members as listed in the Load Balancing Version Activations for Application Load Balancer section of the data model.Make a POST request to
/cloudlets/api/v2/origins/{originId}/activations
, specifying the JSON in the body of the request.
List policy activations
Returns the complete activation history for the selected policy in reverse chronological order.
For this operation, you have the option of using the network
and the
propertyName
query parameters to narrow the number of results
returned. If using the network
parameter, you can enter either
staging
or production
. For the propertyName
parameter, you need
to know the name of the property associated with the Cloudlets policy
versions you want a list of.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
policyId |
Number | 11754 |
The ID of the policy. |
Optional | |||
network |
String | prod |
Returns only activations for the selected network, either staging or prod . |
propertyName |
String | prod |
Returns only activations for the selected property. |
Status 200
application/json
Response Body:
[
{
"serviceVersion": null,
"apiVersion": "2.0",
"network": "staging",
"policyInfo":
{
"policyId": 2962,
"name": "RequestControlPolicy",
"version": 1,
"status": "ACTIVE",
"statusDetail": "File successfully deployed to Akamai's network",
"detailCode": 4000,
"activationDate": 1427428800000,
"activatedBy": "jsmith"
},
"propertyInfo":
{
"name": "www.rc-cloudlet.com",
"version": 0,
"groupId": 40498,
"status": "INACTIVE",
"activatedBy": null,
"activationDate": 0
}
}
]
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Make a GET request to
/cloudlets/api/v2/policies/{policyId}/activations
, which returns a list of activations for a specific policy.
Activate a policy version
Activate the selected cloudlet policy version. After activation completes, the Cloudlets policy is ready for use.
You can activate a policy version with a POST operation against the
../policies/{version}/activations
endpoint, if you
include the network
and version
JSON members.
If you include the network
attribute in the request body, you can
also activate a policy version by issuing a POST to the
/cloudlets/api/v2/policies/{policyId}/versions/{version}/activations
endpoint.
In addition, if the property version that references the Cloudlet policy is activated, an activation record is created.
The property activation status is either active
or inactive
.
NOTE: If you are using NetStorage, review the NetStorage Activation Considerations section.
POST /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
policyId |
Number | 11754 |
The ID of the policy. |
async |
Boolean | true |
When enabled, the activation occurs asynchronously in the background. To check for completion, run the Get a policy version operation, then check one of the response’s activations for a status value of active . Recommended for activations on a high number of properties. Currently, it is supported for API Prioritization (AP ), Application Load Balancer (ALB ), Phased Release (CD ), Request Control (IG ) and Visitor Prioritization (VP ). |
version |
Number | 10 |
The version number of the policy. |
If not done already, use the Property Manager API (PAPI) to set up the behavior for each Cloudlet you are configuring:
Run the List Policies operation.
Store the
policyId
from the appropriate object within the listing.Run the List Policy Versions operation.
Store the
version
from the appropriate object within the listing.Run the Get Associated Properties for a Policy operation.
Store the
name
of any property that you want to associate with the policy version being activated.Create a JSON file with information about the
network
to activate on (staging
orproduction
), as well as any optional properties to associate with Cloudlets policy version.Make a POST request to
/cloudlets/api/v2/policies/{policyId}/versions/{version}/activations
, specifying the JSON in the body of the request.
Get a schema
Get a JSON schema for interacting with policies to validate different requests used with this API.
For the request’s schemaName
, use one the following, where
cloudletType
corresponds to the cloudletCode
available from List
Cloudlets.
Action to Validate | JSON Schema Name |
---|---|
Create a new policy | create-policy.json |
Update a policy | update-policy.json |
Clone an existing policy | clone-policy.json |
Create or clone a policy version | create-nimbus_policy_version-{cloudletType}-1.0.json |
Update a policy version | update-nimbus_policy_version-{cloudletType}-1.0.json |
Create or update a match rule | match_rule-{cloudletType}-1.0.json |
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
schemaName |
String | create-policy.json |
The name of the JSON schema file. |
Status 200
application/json
Response Body:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "CREATE POLICY",
"description": "applied to requests to create policies of the form: POST /cloudlets/api/v2/policies",
"version" : "1.0",
"location" : "/cloudlets/api/v2/schemas/create-policy.json",
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z_A-Z0-9]+$",
"maxLength": 64
},
"cloudletId": {
"type": "integer",
"enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8 ]
},
"description": {
"type": [ "string", "null" ],
"maxLength": 255
},
"propertyName": {
"type": [ "string", "null" ],
"pattern": "^[a-z_A-Z0-9\\.\\-]+$"
},
"groupId": {
"type": "integer"
}
},
"required": [ "cloudletId", "name" ],
"additionalProperties": false
}
List schemas per Cloudlet
Get links to all the JSON schemas by Cloudlet type (cloudletCode
) to
validate different requests used with this API. See List
Cloudlets
for information on how to obtain the cloudletCode
.
GET /cloudlets/
Sample: /cloudlets/
Parameter | Type | Sample | Description |
---|---|---|---|
Optional | |||
cloudletType |
String | ER |
The two- or three- letter code of the Cloudlet you want to view all schemas for. This value corresponds to the cloudletCode member available from List Cloudlets. |
Status 200
application/json
Response Body:
{
"schemas":
[{
"title": "EDGE REDIRECTOR MATCH RULE",
"version": "1.0",
"location": "/cloudlets/api/v2/schemas/match_rule-ER-1.0.json",
"description": "applied to create/update match rule requests for ER cloudlets, where requests are of the form: POST|PUT /api/v2/policies/{policyId}/versions/{versionId}/rules/{ruleId}",
"additionalDescription": "null"
},
{
"title": "CREATE/CLONE POLICY VERSION",
"version": "1.0",
"location": "/cloudlets/api/v2/schemas/create-nimbus_policy_version-ER-1.0.json",
"description": "applied to create/clone policy version requests of form: POST /policies/{policyId}/versions ",
"additionalDescription": "applied to policy version requests for ER cloudlets"
},
{
"title": "UPDATE POLICY VERSION",
"version": "1.0",
"location": "/cloudlets/api/v2/schemas/update-nimbus_policy_version-ER-1.0.json",
"description": "applied to update policy version requests of form: PUT /policies/{policyId}/versions/{versionId} ",
"additionalDescription": "applied to policy version requests for ER cloudlets"
},
{
"title": "CREATE POLICY",
"version": "1.0",
"location": "/cloudlets/api/v2/schemas/create-policy.json",
"description": "applied to requests to create policies of the form: POST /cloudlets/api/v2/policies",
"additionalDescription": "null"
},
{
"title": "UPDATE POLICY",
"version": "1.0",
"location": "/cloudlets/api/v2/schemas/update-policy.json",
"description": "applied to all requests to update policies of the form: PUT /cloudlets/api/v2/policies/{policyId}",
"additionalDescription": "null"
},
{
"title": "CLONE POLICY",
"version": "1.0",
"location": "/cloudlets/api/v2/schemas/clone-policy.json",
"description": "applied to requests to clone policies of the form: POST /cloudlets/api/v2/policies?clonePolicyId=***",
"additionalDescription": "null"
}]
}
Data
This section shows you the data model for the Cloudlets v2 API. The sections are organized based the standard workflow through this API.
In addition, JSON schemas are available for this API. See the JSON Schemas section for a list of schemas.
NOTE: See the Matches section for information about properties available for match rules.
CloudletInfo
The Cloudlet object (CloudletInfo) provides data about the Cloudlets enabled for an account.
When retrieving data for a single Cloudlet, the cloudletId
is
required. This property is returned when you run a GET for all
Cloudlet information.
Sample GET response:
[
{
"apiVersion" : "2.0",
"cloudletCode" : "FR",
"cloudletId" : 3,
"cloudletName" : "FORWARDREWRITE",
"location" : "/api/v2/cloudlet-info/3",
"serviceVersion" : null
},
{
"apiVersion" : "2.0",
"cloudletCode" : "ER",
"cloudletId" : 0,
"cloudletName" : "EDGEREDIRECTOR",
"location" : "/api/v2/cloudlet-info/0",
"serviceVersion" : null
}
]
A 200 response message indicates the network successfully processed the request.
See HTTP Codes for a list of status codes returned with this API.
CloudletInfo members
Member | Type | Description |
---|---|---|
Required | ||
apiVersion |
String | The specific version of this API. |
cloudletCode |
Enumeration | The two- or three- character code for the type of Cloudlet. Possible values include: ALB for Application Load Balancer, AP for API Prioritization, AS for Audience Segmentation, CD for Phased Release, ER for Edge Redirector, FR for Forward Rewrite, IG for Request Control, IV for Input Validation, and VP for Visitor Prioritization. |
cloudletId |
Number | An integer that corresponds to a Cloudlets policy type. |
cloudletName |
Enumeration | The full name of the Cloudlet. The available options for this field are APPLICATIONLOADBALANCER , ASSETPRIORITIZATION for API Prioritization, AUDIENCESEGMENTATION , CONTINUOUSDEPLOYMENT for Phased Release, EDGEREDIRECTOR , FORWARDREWRITE , INPUTVALIDATION , IPGEOACCESS for Request Control, , and VISITORPRIORITIZATION . |
location |
String | The navigable endpoint used for the object referred to in the operation. |
Deprecated | ||
serviceVersion |
String | The build of the software running on the server. |
GroupInfo
The Group-Level Cloudlet object (GroupInfo) provides data about the types of Cloudlets associated with the groups you have edit privileges for. This object supports GET requests that retrieve data either for all groups containing Cloudlets, or for a specific group.
When retrieving data for a single group, the groupId
is required.
Use -1
to request policies from your default group. The groupId
is
returned when you run a GET for all group information. For results to
display, however, you must have edit privileges for one or more
Cloudlet types within the group.
Sample GET response:
[
{
"apiVersion" : "2.0",
"capabilities" : [
{
"capabilities" : [
"View",
"Edit",
"Activate"
],
"cloudletCode" : "ER",
"cloudletId" : 0
}
],
"groupId" : 5678,
"groupName" : "Subgroup 1",
"location" : "/api/v2/group-info/5678",
"parentId" : 1234,
"properties" : ["www.example.com", "www.example.org"],
"serviceVersion" : null
}
]
GroupInfo members
Member | Type | Description |
---|---|---|
Required | ||
apiVersion |
String | The specific version of this API. |
capabilities |
GroupInfo.capabilities[] | An array of type and permission information for each Cloudlet, as detailed below. |
groupId |
Number | The group association for the policy. If 0 , the policy is not tied to a group and in effect appears in all groups for the account. |
groupName |
String | The name of the group. |
location |
String | The navigable endpoint used for the object referred to in the operation. |
parentId |
Number | The ID of the parent group. If you do not have edit permission for the parent group, this value is 0 and the parent group does not appear in the response. |
properties |
Array | An array of the properties associated with the selected group. |
Deprecated | ||
serviceVersion |
String | The build of the software running on the server. |
GroupInfo.capabilities[]
Member | Type | Description |
---|---|---|
Required | ||
capabilities |
Enumeration | The permissions available for that Cloudlet. Possible values include: Activate , Edit , and View . |
cloudletCode |
Enumeration | The two- or three- character code for the type of Cloudlet. Possible values include: ALB for Application Load Balancer, AP for API Prioritization, AS for Audience Segmentation, CD for Phased Release, ER for Edge Redirector, FR for Forward Rewrite, IG for Request Control, IV for Input Validation, and VP for Visitor Prioritization. |
cloudletId |
Number | An integer that corresponds to a Cloudlets policy type. |
Policy
The Cloudlet Policy object (Policy) allows you to create and manage
your Cloudlet policies. When creating a Cloudlet policy, your request
needs to include both the cloudletId
(like 0
for Edge Redirector)
and the groupId
for the Cloudlet you are configuring. In addition, a
name for the policy and a description are required.
Within a Cloudlet policy you set up specific versions, and within these versions you set up the match rules for governing how the Cloudlet is used.
Request and response examples
To create a new policy, you POST to the same endpoint from which you GET your full set of properties.
Sample GET response:
{
"activations" : [
{
"apiVersion" : "2.0",
"network" : "prod",
"policyInfo" : {
"activatedBy" : null,
"activationDate" : 0,
"detailCode" : 0,
"name" : "TestCreatePolicy1",
"policyId" : 1002,
"status" : "INACTIVE",
"version" : 0
},
"propertyInfo" : null,
"serviceVersion" : null
},
{
"apiVersion" : "2.0",
"network" : "staging",
"policyInfo" : {
"activatedBy" : null,
"activationDate" : 0,
"detailCode" : 0,
"name" : "TestCreatePolicy1",
"policyId" : 1002,
"status" : "INACTIVE",
"version" : 0
},
"propertyInfo" : null,
"serviceVersion" : null
}
],
"apiVersion" : "2.0",
"cloudletCode" : "CC",
"cloudletId" : 99,
"createDate" : 1428957069841,
"createdBy" : "jsmith",
"deleted" : false,
"description" : "Creating a policy",
"groupId" : 1234,
"lastModifiedBy" : "jsmith",
"lastModifiedDate" : 1428957069841,
"location" : "/api/v2/policies/1002",
"name" : "CreatePolicy1",
"policyId" : 1002,
"propertyName" : null,
"serviceVersion" : null
}
A 200 response message indicates the network successfully processed the request. A 201 response message indicates that a policy was successfully created.
See HTTP Codes for a list of status codes returned with this API.
Policy members
Member | Type | Description |
---|---|---|
Optional | ||
activations |
Policy.activations[] | An array of current policy activation information, as detailed below. |
apiVersion |
String | The specific version of this API. |
cloudletCode |
Enumeration | The two- or three- character code for the type of Cloudlet. Possible values include: ALB for Application Load Balancer, AP for API Prioritization, AS for Audience Segmentation, CD for Phased Release, ER for Edge Redirector, FR for Forward Rewrite, IG for Request Control, IV for Input Validation, and VP for Visitor Prioritization. |
cloudletId |
Number | Required in POST request, unless you are cloning a policy. Defines the policy type. If you include this property in a clone request, the value must match the policy type of the policy being cloned. Use the Cloudlet Information operations to retrieve this value. |
createdBy |
String | The name of the user who created this specific policy. |
createDate |
Number | The date this specific policy was created (in milliseconds since Epoch). |
deleted |
Boolean | If true , the policy has been deleted. |
description |
String | The description of this specific policy. |
groupId |
Number | Required in POST request, unless you are cloning a policy. Defines the group association for the policy. You must have edit privileges for the group. If 0 , the policy is not tied to a group and in effect appears in all groups for the account. Use -1 to request policies from your default group. |
lastModifiedBy |
String | The user who last modified the policy. |
lastModifiedDate |
Number | The date the initial policy was modified (in milliseconds since Epoch). |
location |
String | The navigable endpoint used for the object referred to in the operation. |
matchRuleFormat |
String | The version of the Cloudlet-specific matchRules . |
matchRules |
Array | A JSON structure that defines the rules for this policy. See Cloudlets API Match Rules for details. |
name |
String | Required in POST request. The name of the policy. The name must be unique. |
policyId |
Number | An integer ID that is associated with all versions of a policy. |
rulesLocked |
Boolean | If true , you cannot edit the match rules for the Cloudlet policy version. |
Deprecated | ||
propertyName |
String | This property now only returns null . It does not reflect the properties currently associated with this Cloudlets policy. |
serviceVersion |
String | The build of the software running on the server. |
Policy.activations[]
Member | Type | Description |
---|---|---|
Required | ||
network |
Enumeration | The network, either staging or prod on which a property or a Cloudlets policy has been activated. |
policyInfo |
Activation.policyInfo | The object containing Cloudlet policy information, as detailed below. |
propertyInfo |
Activation.propertyInfo | The object containing information about the property associated with a particular Cloudlet policy, as detailed below. |
Optional | ||
apiVersion |
String | The specific version of this API. |
Deprecated | ||
serviceVersion |
String | The build of the software running on the server. |
PolicyVersion
The Cloudlets Policy Version object (PolicyVersion) allows you to create and manage versions of your Cloudlet policies.
Sample GET response:
{
"activations" : [
{
"apiVersion" : "2.0",
"network" : "prod",
"policyInfo" : {
"activatedBy" : null,
"activationDate" : 0,
"detailCode" : 0,
"name" : "CreatePolicy1",
"policyId" : 1002,
"status" : "INACTIVE",
"version" : 2
},
"propertyInfo" : null,
"serviceVersion" : null
},
{
"apiVersion" : "2.0",
"network" : "staging",
"policyInfo" : {
"activatedBy" : null,
"activationDate" : 0,
"detailCode" : 0,
"name" : "CreatePolicy1",
"policyId" : 1002,
"status" : "INACTIVE",
"version" : 2
},
"propertyInfo" : null,
"serviceVersion" : null
}
],
"createDate" : 1428957891084,
"createdBy" : "sjones",
"description" : "New version of forwarding policy.",
"lastModifiedBy" : "jsmith",
"lastModifiedDate" : 1428957891084,
"matchRules" : [],
"policyId" : 1002,
"revisionId" : 12345,
"rulesLocked" : false,
"version" : 2
}
PolicyVersion members
Member | Type | Description |
---|---|---|
Optional | ||
activations |
PolicyVersion.activations[] | An array of activation information, as detailed below. |
akaRuleId |
String | The rule’s unique identifier. |
createdBy |
String | The name of the user who created this specific policy. |
createDate |
Number | The date this specific policy was created (in milliseconds since Epoch). |
description |
String | Required for POST request. The description of this specific policy. |
lastModifiedBy |
String | The user who last modified the policy. |
lastModifiedDate |
Number | The date the initial policy was modified (in milliseconds since Epoch). |
matchRuleFormat |
String | Required for POST request. The version of the Cloudlet-specific matchRules . |
matchRules |
Array | A JSON structure that defines the rules for this policy. See Cloudlets API Match Rules for details. |
policyId |
Number | An integer ID that is associated with all versions of a policy. |
revisionId |
Number | Unique ID given to every policy version update. |
rulesLocked |
Boolean | If true , you cannot edit the match rules for the Cloudlet policy version. |
version |
String | The version number of an activated policy (policyInfo ) or property (propertyInfo ). |
PolicyVersion.activations[]
Member | Type | Description |
---|---|---|
Optional | ||
apiVersion |
String | The specific version of this API. |
network |
Enumeration | The network, either staging or prod on which a property or a Cloudlets policy has been activated. |
policyInfo |
Activation.policyInfo | The object containing Cloudlet policy information, as detailed below. |
propertyInfo |
Activation.propertyInfo | The object containing information about the property associated with a particular Cloudlet policy, as detailed below. |
Deprecated | ||
serviceVersion |
String | The build of the software running on the server. |
PropertyAssociation
Use the Property Association object (PropertyAssociation) to find out which versions of a property that is associated with a Cloudlets policy is activated on the production and staging networks.
Sample GET response:
{
"www.myproperty.com": {
"groupId": 40498,
"name": "www.myproperty.com",
"newestVersion": {
"activatedBy": "sjones",
"activationDate": "2015-08-25",
"cloudletsOrigins": {
"nsorigin1": {
"id": "nsorigin1",
"hostname": "origin2.myproperty.com",
"checksum": "0edc0bb1be7439248a77f48e806d2531",
"type": "NETSTORAGE"
},
"clorigin1": {
"id": "clorigin1",
"hostname": "origin1.myproperty.com",
"checksum": "eefa90e680a1183725cfe2a1f00307c4",
"type": "CUSTOMER"
}
},
"version": 5,
"referencedPolicies": ["fr_policy_1"]
},
"production": {
"activatedBy": "jsmith",
"activationDate": "2015-08-26",
"cloudletsOrigins": {
"clorigin2": {
"id": "clorigin2",
"hostname": "origin2.myproperty.com",
"checksum": "0edc0bb1be7439248a77f48e806d2531",
"type": "NETSTORAGE"
},
"clorigin1": {
"id": "clorigin1",
"hostname": "origin1.myproperty.com",
"checksum": "eefa90e680a1183725cfe2a1f00307c4",
"type": "CUSTOMER"
}
},
"version": 5,
"referencedPolicies": ["fr_policy_1"]
},
"staging": {
"activatedBy": "jsmith",
"activationDate": "2015-08-25",
"cloudletsOrigins": {
"nsorigin1": {
"id": "nsorigin1",
"hostname": "origin2.myproperty.com",
"checksum": "0edc0bb1be7439248a77f48e806d2531",
"type": "NETSTORAGE"
},
"clorigin1": {
"id": "clorigin1",
"hostname": "origin1.myproperty.com",
"checksum": "eefa90e680a1183725cfe2a1f00307c4",
"type": "CUSTOMER"
}
},
"version": 5,
"referencedPolicies": ["fr_policy_1"]
}
}
}
PropertyAssociation members
At the top level of the PropertyAssociation object is an arbitrary key that corresponds to the name of a property associated with one or more Cloudlets policies. This property may or may not have Cloudlets Origins configured on it.
This top-level object includes additional objects containing information about the latest version of the property, as well as its status on the production and staging environments. See PropertyAssociation.* below for a description of its members.
PropertyAssociation.*
Members | Type | Description |
---|---|---|
Required | ||
groupId |
Number | The group association for the property. |
name |
String | The name of the property. This value also appears at the start of each separate property object. |
newestVersion |
PropertyAssociation.*.* | An object that contains information about the newest property version. |
production |
PropertyAssociation.*.* | An object that contains information about the property’s current configuration on the production network. |
staging |
PropertyAssociation.*.* | An object that contains information about the property’s current configuration on the staging network. |
PropertyAssociation.*.*
Members | Type | Description |
---|---|---|
Optional | ||
activatedBy |
String | The name of the user who activated property. |
activationDate |
Number | The date on which the property was activated (in ISO 8601 format). |
cloudletsOrigins |
PropertyAssociation.*.*.cloudletsOrigins.* | An object that contains information about each Conditional Origin configured on the property, as described below. |
referencedPolicies |
Array | The names of Cloudlets policies associated with this version of the property. All values in this array are strings. To retrieve policy information, construct a URL with one of the values listed and the id from the PropertyAssociation.*.*.cloudletsOrigins.* object. |
version |
String | The version number of the property. |
PropertyAssociation.*.*.cloudletsOrigins.*
Members | Type | Description |
---|---|---|
Optional | ||
checksum |
String | The checksum that distinguishes this Conditional Origin from any others that might share the same name. |
hostname |
String | The name of the host that can be used as a Conditional Origin. |
id |
String | The Conditional Origin’s unique identifier. |
type |
Enumeration | The type of origin this Conditional Origin is set up as. Options are either CUSTOMER or NETSTORAGE . |
CloudletsOrigin for Application Load Balancer
For the Application Load Balancer Cloudlet, use the Conditional Origin object (CloudletsOrigin) to view information about all types of Conditional Origins, and to set up and maintain load balancing configurations.
Load balancing configurations require a Conditional Origin with an
originType
of APPLICATION_LOAD_BALANCER
.
NOTE: The
/cloudlets/api/v2/conditional-origins?{policyId}
endpoint that was previously used for Conditional Origins has been deprecated. See the Property Association Operations section for operations that return information about Conditional Origins.
Sample GET response:
[
{
"originId": "clorigin1",
"checksum": "abcdefg1111hijklmn22222fff76yae3",
"description": "Test load balancing configuration."
"type": "APPLICATION_LOAD_BALANCER"
}
]
CloudletsOrigin members
Members | Type | Description |
---|---|---|
Optional | ||
checksum |
String | The checksum that distinguishes this Conditional Origin from any others that might share the same name. |
hostname |
String | The name of the host that can be used as a Conditional Origin. |
originId |
String | The Conditional Origin’s unique identifier. |
type |
Enumeration | The type of origin this Conditional Origin is set up as. Options are APPLICATION_LOAD_BALANCER , CUSTOMER , and NETSTORAGE . |
LoadBalancingVersion
The Load Balancing Version (LoadBalancingVersion) object allows you to
set up and maintain separate versions of load balancing configurations
associated with a Conditional Origin. Only Conditional Origins with an
originType
of APPLICATION_LOAD_BALANCER
support load balancing
versions.
Sample GET response:
{
"balancingType": "WEIGHTED",
"createdBy": "jjones",
"createdDate": "2015-10-08T11:42:18.690Z",
"dataCenters": [
{
"cloudService": false,
"livenessHosts": [
"clorigin3.www.example.com",
],
"latitude": 102.78108,
"longitude": -116.07064,
"continent": "NA",
"country": "US",
"originId": "clorigin3",
"percent": 100.0
}
],
"deleted": false,
"description": "Initial load balancing configuration for ALB rollout.",
"immutable": false,
"lastModifiedBy": "ejnovak",
"lastModifiedDate": "2016-05-02T00:40:02.237Z",
"livenessSettings": {
"hostHeader": "clorigin3.www.example.com",
"interval": 25,
"path": "/directory/subdirectory",
"port": 443,
"protocol": "HTTPS",
"status3xxFailure": false,
"status4xxFailure": true,
"status5xxFailure": false,
"timeout": 30
},
"originId": "clorigin1",
"version": 4
}
LoadBalancingVersion members
Member | Type | Description |
---|---|---|
Required | ||
balancingType |
Enumeration | The type of load balancing being performed. Options include WEIGHTED and PERFORMANCE . |
dataCenters |
LoadBalancingVersion.dataCenters[] | The object containing information on Conditional Origins being used as data centers for an Application Load Balancer implementation, as detailed below. Only Conditional Origins with an originType of CUSTOMER or NETSTORAGE can be used as data centers in an Application Load Balancer configuration. |
deleted |
Boolean | If true , the Conditional Origin version has been deleted. If you set this member to false , you can use this version again. |
description |
String | The description of the load balancing configuration provided by a user. |
Optional | ||
createdBy |
String | The name of the user who created this load balancing configuration. |
createdDate |
String | The date, in ISO 8601 format, when this load balancing configuration was created. |
lastModifiedBy |
String | The user who last modified the load balancing configuration. |
lastModifiedDate |
String | The date, in ISO 8601 format, when the initial load balancing configuration was last modified. |
livenessSettings |
CloudletsOrigin.livenessSettings | The object containing information on the liveness settings for an Application Load Balancer implementation, as detailed below. |
originId |
String | Unique identifier for the Conditional Origin that supports the load balancing configuration. The Conditional Origin must have an originType of APPLICATION_LOAD_BALANCER . The originType is defined in the Origin behavior. |
version |
Number | The version number of the load balancing configuration. |
LoadBalancingVersion.dataCenters[]
Member | Type | Description |
---|---|---|
Required | ||
continent |
String | The continent on which the data center is located. See Continent Codes for a list of valid codes. |
country |
String | The country in which the data center is located. See Country Codes for a list of valid codes. |
latitude |
Number | The latitude value for the data center. This member supports six decimal places of precision. |
longitude |
Number | The longitude value for the data center. This member supports six decimal places of precision. |
originId |
String | The ID of an origin that represents the data center. The Conditional Origin, which is defined in the Property Manager API, must have an originType of either CUSTOMER or NET_STORAGE . The originType is defined in the Origin behavior. |
percent |
Number | The percent of traffic that is sent to the data center. The total for all CloudletsOrigin.dataCenters[] objects within the array must equal 100%. |
Optional | ||
city |
String | The city in which the data center is located. |
cloudService |
Boolean | If true caching for the data center is updated at a certain interval, like it would for a cloud-based service. |
livenessHosts |
Array | An array of strings that represent the origin servers used to poll the data centers in an Application Load Balancer configuration. These servers support basic HTTP polling. |
stateOrProvince |
String | The state, province, or region where the data center is located. |
LoadBalancingVersion.livenessSettings
Member | Type | Description |
---|---|---|
Required | ||
path |
String | The path to the test object used for liveness testing. The function of the test object is to help determine whether the data center is functioning. |
port |
Number | The port for the test object. The default port is 80, which is standard for HTTP. Enter 443 if you are using HTTPS. |
protocol |
Enumeration | The protocol or scheme for the database, either HTTP or HTTPS . |
status3xxFailure |
Boolean | Set to true to mark the liveness test as failed when the request returns a 3xx (redirection) status code. |
status4xxFailure |
Boolean | Set to true to mark the liveness test as failed when the request returns a 4xx (client error) status code. |
status5xxFailure |
Boolean | Set to true to mark the liveness test as failed when the request returns a 5xx (server error) status code. |
Optional | ||
additionalHeaders |
Object | Maps additional case-insensitive HTTP header names included to the liveness testing requests. |
hostHeader |
String | Deprecated. |
immutable |
Boolean | Denotes whether you can edit the load balancing version. The default setting for this member is false . It automatically becomes true when the load balancing version is activated for the first time. |
interval |
Number | How often the liveness test occurs in seconds. Optional defaults to 60 seconds, minimum is 10 seconds. |
timeout |
Number | The number of seconds the system waits before failing the liveness test. The default is 25 seconds. |
LoadBalancingVersionActivations
For the Application Load Balancer Cloudlet, use the Load Balancing
Version Activation object (LoadBalancingVersionActivations) to
activate a specific load balancing version on the network you
select. Only Conditional Origins with an originType
of
APPLICATION_LOAD_BALANCER
can support load balancing configurations.
Sample GET response:
[
{
"activatedBy": "jjones",
"activatedDate": "2016-04-07T18:41:34.251Z",
"network": "PRODUCTION",
"originId": "clorigin1",
"status": "active",
"dryrun": false,
"version": 1
}
]
LoadBalancingVersion.activations
Member | Type | Description |
---|---|---|
Required | ||
network |
Enumeration | Required in POST request. The network, either STAGING or PRODUCTION , on which a load balancing configuration for Application Load Balancer has been activated. |
originId |
String | Unique identifier for the load balancing configuration. |
version |
String | The version number of the activated load balancing configuration. |
Optional | ||
activatedBy |
String | The name of the user who activated the load balancing configuration. |
activatedDate |
String | The date, in ISO 8601 format, on which the load balancing configuration was activated. |
dryrun |
Boolean | If true , the operation validates the configuration, but does not activate the load balancing version. The default setting is false . |
status |
Enumeration | The activation status for the load balancing version. Values include the following: inactive where the load balancing version has not been activated. No active property versions reference this policy. active where the load balancing version is currently active (published) and its associated property version is also active. deactivated where the load balancing version was previously activated but it has been superseded by a more recent activation of another load balancing version. pending where the load balancing version is proceeding through the activation workflow. failed where the activation workflow for the load balancing version has failed. |
Policy activation
To use the Activation object (Activation), you need to know the
version of the policy you want to activate or view. The version
member, which is returned with policy version operations, provides
this information.
Sample GET response:
[
{
"serviceVersion": null,
"apiVersion": "2.0",
"network": "staging",
"policyInfo": {
"policyId": 3235,
"name": "sampleERpolicy",
"version": 2,
"status": "pending",
"statusDetail": "batched",
"detailCode": 1000,
"activatedBy": "sjones",
"activationDate": 1444929490000
},
"propertyInfo": {
"name": "app_cloudlets.xml",
"version": 1,
"groupId": 40498,
"status": "deactivated",
"activatedBy": "jsmith",
"activationDate": 1410825600000
}
}
]
Activation members
Member | Type | Description |
---|---|---|
Optional | ||
additionalPropertyNames |
Array | An array of one or more additional properties that you want to activate with the Cloudlet policy. Once activated, the property and policy are permanently associated with each other. |
apiVersion |
String | The specific version of this API. |
network |
Enumeration | Required in POST request. The network, either staging or prod , on which a property or a Cloudlets policy has been activated. |
policyInfo |
Activation.policyInfo | The object containing Cloudlet policy information, as detailed below. |
propertyInfo |
Activation.propertyInfo | The object containing information about the property associated with a particular Cloudlet policy, as detailed below. |
Deprecated | ||
serviceVersion |
String | The build of the software running on the server. |
Activation.policyInfo
Member | Type | Description |
---|---|---|
Optional | ||
activatedBy |
String | The name of the user who activated the policy. |
activationDate |
Number | The date on which the policy was activated (in milliseconds since Epoch). |
detailCode |
Number | Akamai internal activation status codes. |
name |
String | The name of the policy. |
policyId |
Number | An integer ID that is associated with all versions of a policy. |
status |
Enumeration | The activation status for the policy or property. Values include the following: inactive where the policy version has not been activated. No active property versions reference this policy. active where the policy version is currently active (published) and its associated property version is also active. deactivated where the policy version was previously activated but it has been superseded by a more recent activation of another policy version. pending where the policy version is proceeding through the activation workflow. failed where the policy version activation workflow has failed. |
statusDetail |
String | Information about the status of an activation operation. This field is not returned when it has no value, and it never has a value for fast activation Cloudlets such as Visitor Prioritization or Phased Release. |
version |
String | The version number of the activated policy. |
Activation.propertyInfo
Member | Type | Description |
---|---|---|
Optional | ||
activatedBy |
String | The name of the user who activated the property. |
activationDate |
Number | The date on which the property was activated (in milliseconds since Epoch). |
groupId |
Number | Defines the group association for the policy or property. If 0 , the policy is not tied to a group and in effect appears in all groups for the account. You must have edit privileges for the group. |
name |
String | The name of the property. |
status |
Enumeration | The activation status for the policy or property. Values include the following: inactive where the policy version has not been activated. No active property versions reference this policy. active where the policy version is currently active (published) and its associated property version is also active. deactivated where the policy version was previously activated but it has been superseded by a more recent activation of another policy version. pending where the policy version is proceeding through the activation workflow. failed where the policy version activation workflow has failed. |
version |
String | The version number of the activated property. |
JSON schemas
The following JSON Schemas are available for this API:
Schema Type | JSON Schema Name |
---|---|
Create a new policy | create-policy.json |
Update a policy | update-policy.json |
Clone an existing policy | clone-policy.json |
Create or clone a policy version | create-nimbus_policy_version-{cloudletType}–1.0.json |
Update a policy version | update-nimbus_policy_version-{cloudletType}–1.0.json |
Create or update a match rule | match_rule-{cloudletType}–1.0.json |
Sample GET response:
{
"schemas": [
{
"title": "EDGE REDIRECTOR MATCH RULE",
"version": "1.0",
"location": "/api/v2/schemas/match_rule-ER-1.0.json",
"description": "applied to create/update match rule requests for ER cloudlets, where requests are of the form: POST|PUT /api/v2/policies/{policyId}/versions/{versionId}/rules/{ruleId}",
"additionalDescription": "null"
},
{
"title": "CREATE/CLONE POLICY VERSION",
"version": "1.0",
"location": "/api/v2/schemas/create-nimbus_policy_version-ER-1.0.json",
"description": "applied to create/clone policy version requests of form: POST /policies/{policyId}/versions ",
"additionalDescription": "applied to policy version requests for ER cloudlets"
},
{
"title": "UPDATE POLICY VERSION",
"version": "1.0",
"location": "/api/v2/schemas/update-nimbus_policy_version-ER-1.0.json",
"description": "applied to update policy version requests of form: PUT /policies/{policyId}/versions/{versionId} ",
"additionalDescription": "applied to policy version requests for ER cloudlets"
},
{
"title": "CREATE POLICY",
"version": "1.0",
"location": "/api/v2/schemas/create-policy.json",
"description": "applied to requests to create policies of the form: POST /cloudlets/api/v2/policies",
"additionalDescription": "null"
},
{
"title": "UPDATE POLICY",
"version": "1.0",
"location": "/api/v2/schemas/update-policy.json",
"description": "applied to all requests to update policies of the form: PUT /cloudlets/api/v2/policies/{policyId}",
"additionalDescription": "null"
},
{
"title": "CLONE POLICY",
"version": "1.0",
"location": "/api/v2/schemas/clone-policy.json",
"description": "applied to requests to clone policies of the form: POST /cloudlets/api/v2/policies?clonePolicyId=***",
"additionalDescription": "null"
}
]
}
Schema members
Member | Type | Description |
---|---|---|
Optional | ||
title |
String | The title of the JSON schema. |
version |
String | The specific version of the JSON schema. |
location |
String | The network path for the JSON schema. |
description |
String | A description of when the JSON schema is applied. |
additionalDescription |
String | Cloudlet-specific information for the JSON schema. |
Match rules
Once a Cloudlet policy has been created, you can then add match rules to an existing version of that policy, or when you create a new policy version.
NOTE: The maximum number of rules per Cloudlets policy is currently 5,000. However, there is no limit to the number of Cloudlets policies you can create.
Working with match rules
When working with Cloudlets match rules, all of the match criteria are
included in the matchRules
array.
Within the matchRules
array, it is common to use the matches
array, which defines potential conditions, like case sensitivity
(caseSensitive
) or the type of match (matchType
). These properties
apply to all Cloudlets.
You use the matchType
properties to set up the part of the request
that the rule applies to, like redirect URL (matchURL
) or path and
query string (pathAndQS
).
For additional examples, see Cloudlet-Specific Match Examples.
When a Cloudlet executes, the first rule applied is the first one that is true based on criteria in the incoming request.
Match rule considerations
When setting up rules for Cloudlets, be aware of the following:
There is currently no way to implement an
else
case in a rule.There are no child rules within Cloudlet policies.
When a new policy is created, version 1 of the policy is also created. This version is empty: it contains neither a description nor any match rules (
matchRules
).If you clone an existing policy, the
matchRules
for version 1 of the new policy are copied from the most recent version of the cloned policy.
Match rule versions
When setting up the rules for a Cloudlet policy version, you first
need to determine the matchRuleFormat
to use. The matchRuleFormat
attribute indicates the version of the Cloudlet-specific matchRules
JSON, and uses the following format: {major}.{minor}
. The major
number always matches the value in the URI pathname
(.../api/{version}/...
). The current major version is 2. The minor
number changes as attributes are added to or removed from the resource
objects.
NOTE: If you issue a PUT or POST request for Cloudlet policy versions that include
matchRules
, you also need to use thematchRuleFormat
property.
Locking rules
The rulesLocked
property is automatically set to true
when a
policy version is activated on a network. When rulesLocked
equals
true
, the policy version’s rules can no longer be edited. No further
PUTs are allowed against the policy version.
If the rules are locked for a policy version, you must create a new policy version to continue editing the policy.
NOTE: If desired, use the cloning parameter,
cloneVersion
, to edit the policy.
Match with wildcards
You can use wildcard characters (*
and ?
) for the following match
types: cookie
, header
, path
, extension
, filename
, query
,
and hostname
.
NOTE: The
cookie
andquery
matches only accept wildcards for the value, not the cookie or query name. For example,"matchValue":"cookiename=m*nster"
would be valid, but"matchValue":"c*kiename=m*nster"
would not.
As a wildcard, the asterisk represents zero or more characters in a string of characters, and the question mark represents a single character.
With the exception of hostname
, when using a wildcard with this API,
you need to set the matchOperator
parameter to contains
. For
hostname
, the contains
setting is not required. If you enter an
asterisk in the hostname
property, it is automatically treated as a
wildcard.
Wildcard match example
In the following example, the first match listed uses a wildcard: the
matchvalue
of /products/wildcards/*.jpg
matches on any .jpg file
in the /products/wildcards/
directory. This is because the
matchOperator
is contains
.
The second match, however, literally looks for a file called *.jpg
because the matchOperator
is equals
.
{
"matchRules": [{
"matchURL": null,
"matches": [{
"matchType": "path",
"matchValue": "/products/wildcards/*.jpg",
"matchOperator": "contains",
"negate": false,
"caseSensitive": false
},
{
"matchType": "path",
"matchValue": "/products/literals/*.jpg",
"matchOperator": "equals",
"negate": false,
"caseSensitive": false
},
"start": 0,
"end": 0,
"type": "apMatchRule",
"useIncomingQueryString": false,
"passThroughPercent": "50",
"name": "RequiredNameField",
"id": null
}
Match with regular expressions
For the Audience Segmentation, Edge Redirector, Forward Rewrite, and Input Validation Cloudlets, you can now use regular expressions to match on the fully qualified incoming request URL.
The regular expression can be up to 256 characters. If your regular
expression includes any characters that have a special use in regular
expressions (like .
, +
, or ?
), you must use a backslash (\
) to
escape each special character.
For Cloudlets, RE2 is supported. RE2 is a library for regular expressions with a C++ interface that uses the finite-state machine (FSM) computational model. Go to Google’s re2 repository or a similar site, for information about RE2’s syntax.
For Edge Redirector, you can also use the information from capture groups in regular expressions to form the redirect URL. For Audience Segmentation and Forward Rewrite you can use the information from capture groups in regular expressions to form the forward path and, if desired, the query string. Input Validation does not support capture groups.
Capture groups allow you to capture incoming information from the
source URL, while substitution patterns allow you to refer to those
capture groups in the modified URL. Substitution patterns use the
backslash character (\
) followed by a number to refer to the capture
groups. For example, \1
is the first capture group, \2
is the
second, etc.
NOTE: The regular expressions match for Cloudlets supports a maximum of nine numbered substitutions using capture groups.
Regular expression match example
The following is an example of a Forward Rewrite match rule that contains a regular expression.
{
"matchRules": [
{
"matches": [
{
"matchType": "regex",
"matchValue": "^https?://(?:[A-z0-9|\\.]*)/(.*)",
"matchOperator": "equals",
"negate": false,
"caseSensitive": false
}
],
"start": 0,
"end": 0,
"type": "frMatchRule",
"forwardSettings": {
"pathAndQS": "/\\1&extra_param=bar",
"useIncomingQueryString": false
},
"id": null
}
],
"matchRuleFormat": "1.0",
"rulesLocked": false
}
In this example, the regular expression value is
^https?://(?:[A-z0-9|\.]*)/(.*)
and the forward path and query
string value containing a substitution pattern is
/\1&extra_param=bar
. When this rule is activated, all requests
to http://www.example.com/path1/path2/home.html?query=foo
would
retrieve content from
http://www.example.com/path1/path2/home.html?query=foo&extra_param=bar
without changing the URL.
Match types that support multiple values
The following matchType
properties support multiple
space-separated values (not names): extension
, hostname
, path
,
and query
. When setting up a rule using these match types, you can
accidentally create a rule that never matches a request, like the
following:
"matches": [
{
"matchType": "query",
"matchValue": "p=x",
"matchOperator": "equals",
"negate": false,
"caseSensitive": false
}
{
"matchType": "query",
"matchValue": "p=y",
"matchOperator": "equals",
"negate": false,
"caseSensitive": false
}
],
The separate match conditions in this example do not work because the
incoming request has to have both p=x
and p=y
, which is not
valid. However, if matchValue:"p=x y"
, it means a match occurs if
either p=x
or p=y
is in the incoming request.
Matches in requests and responses
When adding match rule criteria to the JSON request for a POST or PUT
operation on the /policies/{nnnn}/versions/{n}
endpoint, you set up
the matchRules
array after defining the matchRuleFormat
. Here, for
example, is a PUT request that adds an Edge Redirector rule with
matches based on the incoming request header:
{
"description" : "Edge Redirector Header Rules",
"matchRuleFormat" : "1.0",
"matchRules" : [
{
"type": "erMatchRule",
"end": 1403127780,
"id": 0,
"matches": [
{
"matchOperator": "contains",
"matchType": "header",
"objectMatchValue": {
"type": "object",
"name": "contentType",
"nameCaseSensitive": false,
"nameHasWildcard": false,
"options": {
"value": [
"text/html*",
"text/css*",
"application/x-javascript*"
],
"valueHasWildcard": true,
"valueCaseSensitive": false
}
}
},
{
"matchOperator": "exists",
"matchType": "header",
"objectMatchValue": {
"type": "object",
"name": "Cache-Control",
"nameCaseSensitive": false,
"nameHasWildcard": false
},
"negate": false
}
],
"name": rule1,
"redirectURL": "http://www.redirect.com",
"start": 1403041407,
"statusCode": 301,
"useIncomingQueryString": false
}
NOTE: The response includes the same match information you provided in the request.
Match properties
This section provides information on the various types of properties used with Cloudlets match rules.
Match rules properties
The Match Rules (matchRules
) array contains all of your rules and
includes the following properties, which vary based on the Cloudlet
you are using:
Property | Type | Description | Cloudlets |
---|---|---|---|
allowDeny |
Enumeration | If set to allow , the request is sent to origin when all conditions are true. If deny , the request is denied when all conditions are true. If denybranded , the request is denied and rerouted according to the configuration of the Request Control behavior. |
Request Control |
disabled |
Boolean | Optional. If set to true , disables a rule so it is not evaluated against incoming requests. The default setting is false . |
All |
end |
Integer | The end time for this match. Enter the value in UTC in seconds since the epoch. | All |
forwardSettings |
Object | This property defines data used to construct a new request URL if all conditions are met. If all of the conditions you set are true, then the Edge Server returns an HTTP response from the rewritten URL. The following properties can be used with this object: originId , pathAndQS , percent , and useIncomingQueryString . |
Audience Segmentation, Forward Rewrite |
id |
Integer | Akamai internal use only. | All |
jsInsertion |
Boolean | If set to true , inserts MediaMath’s JavaScript tag into the requested page. |
Cloud Marketing, Cloud Marketing Plus |
matches |
Array | See matches below. |
All |
matchURL |
String | If using a URL match, this property is the URL that the Cloudlet uses to match the incoming request. | Edge Redirector, Forward Rewrite |
name |
String | The name of the rule. | All |
originId |
String | The ID of the Conditional Origin requests are forwarded to. To retrieve the originId , run a GET on the /cloudlets/api/v2/properties endpoint. |
Application Load Balancer, Audience Segmentation, Cloud Marketing, Cloud Marketing Plus, Forward Rewrite, Phased Release |
passThroughPercent |
Number | The range 0.000 : 99.000 specifies the percentage of requests that pass through to the origin. The value of 100 means the request always passes through to the origin. For Visitor Prioritization, a value of -1 means send everyone to the waiting room. |
API Prioritization, Visitor Prioritization |
pathAndQS |
String | If a value is provided and match conditions are met, this property defines the path/resource/query string to rewrite URL for the incoming request. | Audience Segmentation, Forward Rewrite |
redirectURL |
String | The URL Edge Redirector redirects the request to. If using useRelativeUrl , you can enter a path for the value. |
Edge Redirector |
start |
Integer | The start time for this match. Enter the value in UTC in seconds since the epoch. | All |
statusCode |
Integer | The HTTP response status code, which is either 301 (permanent redirect) or 302 (temporary redirect). |
Edge Redirector |
type |
String | The type of Cloudlet the rule is for. For example, the string for Visitor Prioritization is vpMatchRule . |
All |
useIncomingQueryString |
Boolean | If set to true , the Cloudlet includes the query string from the request in the rewritten or forwarded URL. |
Audience Segmentation, Edge Redirector, Forward Rewrite |
useIncomingSchemeAndHost |
Boolean | If set to true , the Cloudlet copies both the protocol/scheme and the hostname from the incoming request to use in the redirect URL. |
Edge Redirector |
useRelativeUrl |
Enumeration | If set to relative_url , takes the path entered for the redirectUrl and sets it in the response’s Location header. The client or browser receiving the request decides which protocol and hostname to use. If set to copy_scheme_hostname , creates an absolute path by taking the protocol and hostname from the incoming request and combining them with path information entered for the redirectUrl . This absolute path is set in the response’s Location header. If this property is not included, or is set to none , then the redirectUrl should be fully-qualified URL. |
Edge Redirector |
Match conditions properties
Each object within the matches
array defines potential conditions,
like case sensitivity (caseSensitive
) or the type of match
(matchType
). These properties apply to all Cloudlets.
A matches
property contains an array of objects with the following
properties/conditions:
Property | Type | Description |
---|---|---|
caseSensitive |
Boolean | If true , the match is case sensitive. |
checkIPs |
Enumeration | For clientip , continent , countrycode , proxy , and regioncode match types, the part of the request that determines the IP address to use. Values include the connecting IP address (CONNECTING_IP ) and the X_Forwarded_For header (XFF_HEADERS ). To select both, enter the two values separated by a space delimiter. When both values are included, the connecting IP address is evaluated first. |
matchOperator |
Enumeration | Valid entries for this property are contains , exists , and equals . |
matchType |
Enumeration | The type of match used. Possible values include the hostname (hostname ) or the cookie (cookie ). See the Match Type Property section. |
matchValue |
String | This depends on the matchType . If the matchType is hostname , then matchValue is the fully qualified domain name, like www.akamai.com . See the examples in the Match Type Property table. |
negate |
Boolean | If true , negates the match. |
objectMatchValue |
Object | An object used when a rule either includes more complex match criteria, like multiple value attributes, or a range match. |
Match value object properties
The following table lists the properties available for the
objectMatchValue
object:
Property | Type | Description |
---|---|---|
type |
Enumeration | The array type, which can be one of the following: object , range , or simple . Use the simple option when adding only an array of string-based values. |
name |
Array | If using a match type that supports name attributes, enter the value in the incoming request to match on. The following match types support this property: cookie , header , parameter , and query . |
nameCaseSensitive |
Boolean | Set to true if the entry for the name property should be evaluated based on case sensitivity. |
nameHasRegex |
Boolean | Set to true if the entry for the name property is a regular expression. |
nameHasWildcard |
Boolean | Set to true if the entry for the name property includes wildcards. |
value |
Array | If using the simple or range array types, enter the value attributes in the incoming request to match on. Valid entries vary by match type. For example, GET and POST are valid entries for the method match type, while any integer is valid for the numberOfFields match type. |
valueCaseSensitive |
Boolean | Set to true if the entries for the value property should be evaluated based on case sensitivity. |
valueHasRegex |
Boolean | Set to true if the entries for the value property includes a capture group for a regular expression. |
valueHasWildcard |
Boolean | Set to true if the entries for the value property includes wildcards. |
options |
Array | If using the object type, use this array to list the values to match on. |
Match type property
The matchType
properties provide information about the match types
used to conditionally pass through the request.
NOTE: Match types with an “m” support multiple space-separated values (not names).
Match Type | Description | Example Match Value |
---|---|---|
all |
A match of all incoming requests. Note that in the Cloudlets Policy Manager application, this match type is called Default . |
Not applicable |
clientip |
The IPv4 address or CIDR list to match on. | 182.1.0.0 |
clientipv6 |
The IPv6 address or CIDR list to match on. | 0:0:0:0:0:ffff:b601:0 |
continent |
The continent to match on. See Continent Codes for a list of valid codes. | SA |
cookie |
The cookie values to match on. | name=value1 |
countrycode |
The country to match on. See Country Codes for a list of valid codes. | US |
deviceCharacteristics |
The device characteristic to match on. See Device Characteristics Match Values for the list of available match values. | is_mobile=true |
extension (m) |
The file extensions to match on. | jpg png gif |
header |
The parts of the request header to match on. | See Matches in Requests and Responses for an example. |
hostname (m) |
The hostnames to match on. | www.akamai.com |
method |
The HTTP method used for the request. | GET |
numberOfFields |
A match based on the number of form fields included in an incoming request. | See Input Validation for an example. |
parameter |
Matches based on the following form parameters: field names and field values. | See Input Validation for an example. |
path (m) |
The URL paths to match on. | /clothing/children/shoes/shoe1.jpg |
protocol |
The protocol to match on. You can only enter a single value in this field. | http |
proxy |
The type of proxy to match on. Values include anonymous , transparent , and both . |
anonymous |
query (m) |
The query string values to match on. | name or name=value1 or name=value1 value2 |
range |
A range of two numbers between 1 and 100 (inclusive) for the random value assigned to a user. If the random value assigned to an incoming request falls within this range, the match is true. | See Audience Segmentation for an example. |
regex |
The regular expression to match on. | ab(c.)d+ |
regioncode |
The region within a country to match on, like a state or province. See Region Codes for a list of valid codes. | MA |
Device characteristics match values
The following values are available for the deviceCharacteristics
match type:
Match Value | Description |
---|---|
accept_third_party_cookie |
Indicates whether the device, by default, accepts a cookie set from a pixel in a page of a different domain. |
ajax_support_javascript |
Indicates whether the device supports asynchronous JavaScript and XML (AJAX), a set of programming techniques. |
cookie_support |
Indicates whether the device’s browser supports cookies. However, this device characteristic does not indicate that cookies exist. In addition, if the value is false because the native browser does not support cookies, cookies may be supported using other methods. |
full_flash_support |
Indicates whether the device has full Flash support. |
is_mobile |
Indicates whether the requesting device is a mobile device. |
is_tablet |
Indicates whether the device is a tablet. |
is_wireless_device |
Indicates whether the device is, or is not, wireless. A mobile phone returns true , but a desktop or laptop returns false . |
Supported match types by Cloudlet
The following table lists, by Cloudlet, the supported match types:
Cloudlet | Supported Match Types | |
---|---|---|
Application Load Balancer | all , clientip , clientipv6 , continent , cookie , countrycode , deviceCharacteristics , extension , header , hostname , method , path , protocol , query , regioncode |
|
API Prioritization | clientip , clientipv6 , continent , cookie , countrycode , deviceCharacteristics , extension , header , hostname , method , path , protocol , proxy , query , regioncode |
|
Audience Segmentation | clientip , clientipv6 , continent , cookie , countrycode , deviceCharacteristics , extension , header , hostname , method , path , protocol , proxy , query , range , regex ,regioncode |
|
Cloud Marketing | clientip , clientipv6 , continent , cookie , countrycode , deviceCharacteristics , extension , header , hostname , method , path , protocol , proxy , query , regioncode |
|
Cloud Marketing Plus | clientip , clientipv6 , continent , cookie , countrycode , deviceCharacteristics , extension , header , hostname , method , path , protocol , proxy , query , regioncode |
|
Edge Redirector | all , clientip , clientipv6 , continent , cookie , countrycode , deviceCharacteristics , extension , header , hostname , method , path , protocol , proxy , query , regex , regioncode |
|
Forward Rewrite | clientip , clientipv6 , continent , cookie , countrycode , deviceCharacteristics , extension , header , hostname , method , path , protocol , proxy , query , regex , regioncode |
|
Input Validation | clientip , clientipv6 , continent , cookie , countrycode , deviceCharacteristics , extension , header , hostname , method , numberOfFields , parameter , path , protocol , proxy , query , regex , regioncode |
|
Phased Release | all , clientip , clientipv6 , continent , cookie , countrycode , deviceCharacteristics , extension , header , hostname , method , path , protocol , proxy , query , regioncode |
|
Request Control | all , clientip , clientipv6 , continent , cookie , countrycode , header , method , path , proxy , query , regioncode , |
|
Visitor Prioritization | clientip , clientipv6 , continent , cookie , countrycode , deviceCharacteristics , extension , header , hostname , method , path , protocol , proxy , query , regioncode |
Cloudlet-specific match examples
For each of the following Cloudlets, this section provides match rule examples:
- Application Load Balancer
- API Prioritization
- Audience Segmentation
- Cloud Marketing
- Cloud Marketing Plus
- Edge Redirector
- Forward Rewrite
- Input Validation
- Phased Release
- Request Control
- Visitor Prioritization
Application Load Balancer
The Application Load Balancer Cloudlet provides intelligent, scalable traffic management across physical, virtual, and cloud-hosted data centers without requiring the origin to send load feedback. This Cloudlet can automatically detect load conditions and route traffic to the optimal data source while maintaining custom routing policies and consistent visitor session behavior for your visitors.
Match rule example
For the following Application Load Balancer match rule, any URL that
uses the HTTP protocol, has a domain name of source.com
, and
includes test=null
as a query string is sent to the appropriate data
center based on the load balancing settings.
{
"matchRules": [{
"type": "albMatchRule",
"matches": [{
"caseSensitive": false,
"matchOperator": "contains",
"matchType": "protocol",
"matchValue": "http",
"negate": false
},
{
"caseSensitive": false,
"matchOperator": "contains",
"matchType": "query",
"matchValue": "test=null",
"negate": false
}],
"name": "rule 1",
"disabled": false,
"forwardSettings":{"originId":"ALBOrigin_1"},
"useIncomingQueryString": false
}]
}
API Prioritization
API Prioritization allows you to specify, for applications that call resources of various formats (like JSON or XML), which calls are given priority and are sent to the origin during high-demand situations. Based on information in the inbound request, you configure the rules that determine which calls are prioritized.
Match rule example
For this example, if the incoming URL has an extension of .jsp, 50% of the time the static response is served.
{
"matchRules": [{
"matchURL": null,
"matches": [{
"matchType": "extension",
"matchValue": "jsp",
"matchOperator": "equals",
"negate": false,
"caseSensitive": false
}],
"start": 0,
"end": 0,
"disabled": false,
"type": "apMatchRule",
"useIncomingQueryString": false,
"passThroughPercent": "50",
"name": "RequiredNameField",
"id": null
}]
}
Audience Segmentation
Audience Segmentation provides traffic segmentation and stickiness without degrading performance, which is often beneficial for A/B and multivariate testing. This Cloudlet creates stable test populations by assigning a cookie value to the user based on the rules you define.
This Cloudlet supports a range match. When setting up a range match, enter the two numbers that comprise the range. If the random value assigned to an incoming request falls within this range (inclusive), the match is true.
NOTE: You can only include one Range Match per rule.
Match rule example
For this example, if the incoming request is assigned a value between
1 and 25 (inclusive), the request is forwarded to the /sales/Q1
directory. Any query strings from the incoming request is appended to
the forward request URL.
{
"matchRules": [{
"matches": [{
"matchType": "range",
"objectMatchValue": {"type": "range","value": [1,25]},
"matchOperator": "equals","negate": false,"caseSensitive": false}],
"start": 0,
"end": 0,
"disabled": false,
"type": "asMatchRule",
"forwardSettings": {
"originId": "originremote2",
"useIncomingQueryString": true,
"pathAndQS": "/sales/Q1/"},
"name": "Q1SalesTestPop",
"id": null
}]
}
Cloud Marketing
If you are a MediaMath customer, Cloud Marketing allows you to add JavaScript tags to your site’s pages that can communicate with MediaMath without requiring a third-party call on every page.
Match rule example
For this match rule, if the incoming URL includes /content/sales/
in
its path, then the MediaMath JavaScript tags are added to the
requested page.
{
"matchRules": [{
"name": "JS_Insertion_for_Sales",
"type": "mmbMatchRule",
"start": 0,
"end": 0,
"id": 0,
"matchURL": null,
"matches": [{
"caseSensitive": false,
"matchOperator": "contains",
"matchType": "path",
"matchValue": "/content/sales/",
"negate": false
}],
"jsInsertion": true,
"disabled": false,
}]
}
Cloud Marketing Plus
If you are a MediaMath customer, Cloud Marketing allows you to add JavaScript tags to your site’s pages that can communicate with MediaMath and its partners without requiring a third-party call on every page.
Match rule example
For this match rule, if the incoming URL includes /content/sales/
in
its path, then the MediaMath JavaScript tags are added to the
requested page.
{
"matchRules": [{
"name": "JS_Insertion_for_Sales",
"type": "mmbMatchRule",
"start": 0,
"end": 0,
"id": 0,
"matchURL": null,
"matches": [{
"caseSensitive": false,
"matchOperator": "contains",
"matchType": "path",
"matchValue": "/content/sales/",
"negate": false
}],
"jsInsertion": true,
"disabled": false
}]
}
Edge Redirector
Edge Redirector helps you more efficiently manage large numbers of redirects. By executing redirects at the Akamai Edge, you can reduce round trips to the origin and offload hits from your origin infrastructure.
Match rule example
For the following Edge Redirector match rule, any URL that uses the
HTTP protocol, has a domain name of example.com
, and includes
test=null
as a query string redirects to the following URL
http://testredirect.akamai.com/test.html
.
{
"matchRules": [{
"type": "erMatchRule",
"end": 0,
"id": 0,
"matchURL": null,
"matches": [{
"caseSensitive": false,
"matchOperator": "contains",
"matchType": "protocol",
"matchValue": "http",
"negate": false
},
{
"caseSensitive": false,
"matchOperator": "contains",
"matchType": "hostname",
"matchValue": "example.com",
"negate": false
},
{
"caseSensitive": false,
"matchOperator": "contains",
"matchType": "query",
"matchValue": "test=null",
"negate": false
}],
"name": "rule 1",
"redirectURL": "HTTP://testredirect.akamai.com/test.html",
"disabled": false,
"start": 0,
"statusCode": 302,
"useIncomingQueryString": false
}]
}
Forward Rewrite
Forward Rewrite helps you create, based on in-bound request information, human-readable and search engine optimization-friendly (SEO-friendly) URLs for dynamically-generated pages.
Match rule example
For this match rule, if the incoming URL has http
for the protocol
or the hostname includes example1.com
, the forward URL has the
following path appended to it: /test_images/simpleimg.jpg
.
{
"matchRules": [{
"type": "frMatchRule",
"disabled": false,
"end": 0,
"id": 0,
"matchURL": null,
"forwardSettings": {
"pathAndQS": "/test_images/simpleimg.jpg",
"useIncomingQueryString": true },
"matches": [{
"caseSensitive": false,
"matchOperator": "contains",
"matchType": "protocol",
"matchValue": "http",
"negate": false
},
{
"caseSensitive": false,
"matchOperator": "contains",
"matchType": "hostname",
"matchValue": "example1.com",
"negate": false
}],
"name": "rule 1",
"start": 0
}]
}
Input Validation
The Input Validation Cloudlet helps protect your business by confirming that the values submitted into a web application are well-formed and comply with your policies. In addition, this Cloudlet lets you to limit the number of valid form submissions and invalid attempts per user. Once the limit is reached, additional requests are denied (403) or are redirected (302) to a custom “penalty box.”
Match rule example
For the following Input Validation rule, a match is valid if the
request uses the HTTP POST method; includes exactly five fields; and,
of those five fields, one of them is called User
.
{
"matchRules": [{
"type": "ivMatchRule",
"disabled": false,
"id": 0,
"matches"[{
"caseSensitive": false,
"matchOperator": "equals",
"matchType": "method",
"negate": false,
"objectMatchValue": {"type": "simple","value": ["POST"]}
},
{
"caseSensitive": false,
"matchOperator": "equals",
"matchType": "numberOfFields",
"negate": false,
"objectMatchValue": {"type": "simple","value": ["5"]}
},{
"caseSensitive": false,
"matchOperator": "required",
"matchType": "parameter",
"negate": false,
"objectMatchValue": {"type": "object","name": "User","options": {"value": []}
}
}],
"name": "SubscriberValidation",
"start": 0},
"end": 0
}
Phased Release
Phased Release provides, at the edge, a mechanism to define a percentage of your visitors and direct them to a different origin while maintaining visitor stickiness. This Cloudlet can help facilitate a fast rollout of code changes to production with real users, allowing you to move some visitors to a new experience or deployment while retaining the flexibility to roll back immediately should you encounter challenges.
Match rule example
For this Phased Release example, 30% of the incoming requests from the
23.235.39.74
IP address are forwarded to the mynetstorage
Cloudlet
origin.
{
"matchRules": [{
"matches": [{
"matchType": "clientip",
"matchValue": "23.235.39.74",
"checkIPs": "CONNECTING_IP",
"matchOperator": "equals",
"negate": false,
"caseSensitive": false}],
"start": 0,
"end": 0,
"disabled": false,
"type": "cdMatchRule",
"forwardSettings": {
"percent": 30,
"originId": "mynetstorage"},
"name": "IP_39.74_rule",
"id": null
}]
}
Request Control
Request Control allows you to provide conditional access to your website or application by defining and managing whitelists and blacklists based on a number of match criteria, including the IP address and geography associated with incoming requests.
Match rule example
For the following Request Control match rule, a request from the
72.246.0.0/16
or 192.0.2.0
address or from the United States are
allowed through to the site.
{
"matchRules": [{
"type": "igMatchRule",
"end": 0,
"id": 0,
"matches": [{
"caseSensitive": false,
"matchOperator": "contains",
"matchType": "clientip",
"matchValue": "72.246.0.0/16 192.0.2.0",
"checkIPs": "CONNECTING_IP XFF_HEADERS",
"negate": false
},
{
"caseSensitive": false,
"matchOperator": "contains",
"matchType": "countrycode",
"matchValue": "US",
"checkIPs": "CONNECTING_IP",
"negate": false
}],
"name": "rule 1",
"disabled": false,
"allowDeny":"denybranded",
"start": 0
}]
}
Visitor Prioritization
Visitor Prioritization helps maintain business continuity for your dynamic application through the use of a waiting room page in high-demand situations.
Match rule example
For the following Visitor Prioritization match rule, any URL that uses
the HTTP protocol, has a domain name of source.com
, and includes
test=null
as a query string, bypasses the waiting room and is sent
directly to the origin.
{
"matchRules": [{
"type": "vpMatchRule",
"end": 0,
"id": 0,
"matchURL": null,
"matches": [{
"caseSensitive": false,
"matchOperator": "contains",
"matchType": "protocol",
"matchValue": "http",
"negate": false
},
{
"caseSensitive": false,
"matchOperator": "contains",
"matchType": "query",
"matchValue": "test=null",
"negate": false
}],
"name": "rule 1",
"disabled": false,
"start": 0,
"passThroughPercent":11,
"useIncomingQueryString": false
}]
}
Errors
If you encounter a variety of errors, the Cloudlets API responds with appropriate HTTP status codes and a response object that explains them, detailed below. There are many possible causes for failure, such as malformed JSON or missing fields.
Error responses
The Cloudlets API responds with HTTP problem error objects that provide details useful for debugging.
The following is an example of a response with a validation error:
{
"detail": "Exceeds maximum rules (5000). Received rule count:5001",
"errorCode": -1,
"errorMessage": "Exceeds maximum rules (5000). Received rule count:5001",
"instance": "2d8290b4-30df-4025-88a8-3f596a52aef7",
"status": 400,
"title": "Too Many Rules",
"type": "/cloudlets/error-types/policy-rule-count-exceeded",
"maxRules": 5000,
"ruleCount": 5001
}
In the response above, the error is caused by the fact that the number of rules allowed per policy has been exceeded. To resolve this issue, divide your rules up between different policies to avoid the rule maximum.
The errorCode
and errorMessage
members are currently included to
maintain backwards compatibility with earlier error messaging formats.
These members will be removed sometime during the third quarter of 2017,
and will eventually disappear.
HTTP codes
The following are common HTTP codes that are used by this API:
Code | Description |
---|---|
200 | OK. The operation was successful. |
201 | Created. |
204 | No content. Displays when a DELETE operation is successful. |
400 | Bad Request. Please provide all the required parameters. |
403 | User is not authenticated. |
404 | Not Found. The object you were trying to reach could not be found. |
409 | Validation exception. For example, you might receive this status if a policy already exists with the same policy name. In the case of a duplicate policy name, the message body contains data for the existing policy. |
429 | Too Many Requests. This code may appear if the API caller is rate limited. |
500 | There is a problem processing your request. Please try again later. The details are provided in the response body. For example, the request may be missing a required parameter. |