Akamai Sandbox API v1

Create an isolated sandbox environment to test site changes and Akamai property configurations locally before deploying to the content delivery network.

Learn more:


Overview

Resolving issues with your website and applications after a property is pushed to the content delivery network is inefficient and a drain on resources. With Sandbox, you can tweak your site delivery options and test in an isolated development environment to identify issues locally before merging.

Incorporate the Sandbox API into your agile development workflow to improve efficiency and identify potential issues well in advance of deployment. Quickly test and validate code changes on your local development server through a secure connection to your sandbox.

Create a sandbox based on:

  • an existing Akamai property, which contains rules for how your website and applications process requests.

  • a specific rule tree.

  • a sandbox preconfigured by another developer within your Control Center group.

Who should use this API

Developers who want to test site and Akamai property changes within an isolated development environment.

Getting started

  1. Create an API client in Control Center for the Sandbox API with read-write access. Follow the steps in Get Started with APIs to learn how to create authentication credentials to access the API.

    NOTE: In order to use the Create a sandbox operation, add authorization for both Property Manager and Sandbox in the API client. If you do not have authorization for Property Manager enabled in the API client, you can only create a sandbox with the Clone a sandbox operation.

  2. Download and configure the Sandbox Client, a proxy server that routes bidirectional requests between your development machine and the Akamai network via a secure gateway. Follow the Configure your Sandbox client instructions in the user guide.

Hypermedia

This API supports a hypermedia-based workflow. When available, the API provides relative links to execute related operations, indicated as href elements in the response object.

The hypermedia format follows the Hypertext Application Language (HAL) standard. You will see the link relations in the response body prefixed by a _links data member.

In this example, self indicates a rule tree object, with other available links to GET the property or sandbox that contains it:

"_links": {
    "self": {
        "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002/rules"
    },
    "sandbox": {
        "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002"
    },
    "property": {
        "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002"
    }
}

Resource limiting

There is a limit of 100 sandbox instances for each Control Center account. The X-Limit-Sandboxes-Remaining value in the response header indicates how many Sandbox instances you have remaining to create.

Resources

The first thing you’ll do with the Sandbox API is Create a sandbox. You can mark the sandbox clonable to make it easier for other developers to quickly create an instance in their local environment with the same settings.

NOTE: If you do not have authorization for Property Manager configured in your API client, you can only create a sandbox with the Clone a sandbox operation.

Familiarize yourself with these concepts before using the Sandbox API.

  • Sandbox: An isolated environment configured for an individual developer that replicates the functionality of an Akamai server. The sandbox communicates with the developer’s origin through a secure, bidirectional connection.

  • JSON Web Token: Also referred to as a JWT, allows the Sandbox client to authenticate your sandbox to the network. Returned in the response object of the Create a sandbox operation. You can also Rotate the JWT to prevent access to the sandbox by anyone who had a previous token.

  • Property: Also referred to as a configuration, provides the main way to control how Akamai servers respond to end-user requests for web content. Properties apply rules to a set of hostnames. Each sandbox contains at least one property.

  • Rule tree: Defines which browser requests to process and the behaviors to apply to those requests. Each property features one rule tree. You can create a sandbox based on a specific rule tree.

  • Hostname: The portion of the URL end users enter into a browser to access your web content, such as www.example.com or dev.example.com . Within a sandbox, a property is associated with at least one hostname. Akamai uses the hostname to determine which rule tree to apply to the request.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List sandboxes GET /sandbox-api/v1/sandboxes
Create a sandbox POST /sandbox-api/v1/sandboxes
Get a sandbox GET /sandbox-api/v1/sandboxes/{sandboxId}
Modify a sandbox PUT /sandbox-api/v1/sandboxes/{sandboxId}
Delete a sandbox DELETE /sandbox-api/v1/sandboxes/{sandboxId}
Rotate the JWT POST /sandbox-api/v1/sandboxes/{sandboxId}/rotateJWT
Clone a sandbox POST /sandbox-api/v1/sandboxes/{sandboxId}/clone
List properties GET /sandbox-api/v1/sandboxes/{sandboxId}/properties
Add a property to a sandbox POST /sandbox-api/v1/sandboxes/{sandboxId}/properties
Read a property GET /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}
Update a property PUT /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}
Delete a property DELETE /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}
Get a rule tree GET /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}/rules
Update a rule tree PUT /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}/rules

List sandboxes

This operation returns a list of sandboxes available to the current user. In the response object, you can see the sandboxId, the developer who created the sandbox, and the sandbox name. You will only see the information for sandboxes you created. The X-Limit-Sandboxes-Remaining in the response header indicates the number of remaining sandboxes you can create.

GET /sandbox-api/v1/sandboxes

Status 200 application/json

Headers:

X-Limit-Sandboxes-Limit: 100
X-Limit-Sandboxes-Remaining: 99

Object type: CreateSandbox

Download schema: Sandboxes.json

Response Body:

{
    "accountId": "B-3-16O",
    "sandboxes": [
        {
            "sandboxId": "a7123f13-6f14-11e8-8592-0242ac110002",
            "createdBy": "devops@example.com",
            "name": "STAR-04",
            "_links": {
                "self": {
                    "href": "/sandbox-api/v1/sandboxes/a7123f13-6f14-11e8-8592-0242ac110002"
                },
                "rotateJWT": {
                    "href": "/sandbox-api/v1/sandboxes/a7123f13-6f14-11e8-8592-0242ac110002/rotateJWT"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "/sandbox-api/v1/sandboxes"
        }
    }
}

Create a sandbox

You can create a sandbox from an existing Akamai property or from a rule tree. Refer to the REQUEST Parameters tab to determine how to form your JSON request. Keep in mind that, to create a sandbox with this method, you need to have an API client for the Sandbox API with read-write access and Property Manager authorization enabled in Control Center. Copy the jwtToken in the response object. You need this to configure your Sandbox Client. Refer to the User Guide for instructions.

POST /sandbox-api/v1/sandboxes

Content-Type: application/json

Object type: CreateSandbox

Download schema: PostSandboxFromRulesOrPropertyRequest.json

Request Body:

Create a sandbox based on a hostname within an existing Akamai property:

{  
    "createFromProperty":{  
        "hostname":"www.example.com"
    },
    "name":"test_sandbox"
} 

Create a sandbox based on a specific property version:

{  
    "createFromProperty":{  
        "propertyName":"www.example.com_pm",
        "propertyVersion":23
    },
    "name":"test_sandbox"
} 

Create a sandbox based on a particular property version that can be cloned by other developers:

{  
    "createFromProperty":{  
        "propertyName":"www.example.com_pm",
        "propertyVersion":23
    },
    "name":"test_sandbox",
    "isClonable":true
} 

Create a sandbox based on a rule tree:

{
  "requestHostnames": [
    "store.example.com",
    "portal.example.com"
  ],
  "createFromRules": {
    "rules": {
      "name": "default",
      "children": [
      ],
      "behaviors": [
        {
          "name": "origin",
          "options": {
            "cacheKeyHostname": "ORIGIN_HOSTNAME",
            "compress": true,
            "enableTrueClientIp": false,
            "forwardHostHeader": "REQUEST_HOST_HEADER",
            "httpPort": 80,
            "httpsPort": 443,
            "originSni": true,
            "originType": "CUSTOMER",
            "verificationMode": "PLATFORM_SETTINGS",
            "hostname": "my-origin.example.com",
            "originCertificate": "",
            "ports": ""
          }
        },
        {
          "name": "cpCode",
          "options": {
            "value": {
              "id": 1090207,
              "description": "my cpcode",
              "products": [
                "SPM"
              ],
              "createdDate": 1251013390000,
              "name": "my cpcode"
            }
          }
        },
        {
          "name": "caching",
          "options": {
            "behavior": "MAX_AGE",
            "mustRevalidate": false,
            "ttl": "3m"
          }
        }
      ],
      "options": {
        "is_secure": false
      },
      "variables": [
      ]
    }
  }
}
Parameter Type Description
Required JSON POST body parameters (CHOOSE ONE)
createFromProperty Object Specifies an identifier for the property to include in the sandbox. Mutually exclusive with createFromRules.
createFromRules Object Specifies the rule tree on which to base the sandbox. Mutually exclusive with createFromProperty.
Optional JSON POST body parameters
name String Descriptive name for the new sandbox. If you do not specify a name, the default name will be the sandboxId. You will get an error message if the name is not unique.
isClonable Boolean Indicates whether the sandbox can be cloned by other developers.
edgeHostname String The edge hostname associated with the property as configured in Property Manager.
hostname String The hostname associated with the property as configured in Property Manager. Use this option only if there is a one-to-one correspondence between the hostname and property. This method will fail if more than one property reference the same hostname.
propertyId Number The unique identifier for the property as it appears in Property Manager. You can find this value with the Property Manager API.
propertyName String The name of the property as it appears in Property Manager. Use this if you have more than one property configuration that references the same hostname.
propertyVersion Number Include the version number with any of the other criteria. If not specified, the API will use the version that is active in production. If no such version is found, the call will fail.
requestHostnames Array Specifies the hostnames for the request. Use this option with createFromRules. If you try to createFromProperty with a requestHostname that is not already contained in the property configuration, you may get unexpected results. Sandbox will automatically convert any specified request hostnames to lower case.

Status 200 application/json

Headers:

X-Limit-Sandboxes-Limit: 100
X-Limit-Sandboxes-Remaining: 98
Location: /sandbox-api/v1/sandboxes/7ccfb989-68ce-11e8-bdfe-0242ac110002

Object type: Sandbox

Download schema: Sandbox.json

Response Body:

{
    "sandboxId": "2956607f-854e-11e8-898a-0242ac110002",
    "createdBy": "joe@example.com",
    "createdOn": "2018-10-09T15:20:36.441Z",
    "name": "Sandbox-123",
    "jwtToken": "eyJ0eXA ... qggqqw",
    "isClonable": true,
    "status": "OK",
    "properties": [
        {
            "sandboxPropertyId": "e7b77afe-271b-4159-bdd1-c312ef560cdb",
            "requestHostnames": [
                "foo.exampledevops.com",
                "foobar.abc1234def.com"
            ],
            "additionalRequestHostnamesInProperty": [
                "www.abc1234def.com"
            ],
            "_links": {
                "property": {
                    "href": "/sandbox-api/v1/sandboxes/75496b3f-6ec0-46dd-9c7e-480d6c201a0d/properties/e7b77afe-271b-4159-bdd1-c312ef560cdb"
                },
                "rules": {
                    "href": "/sandbox-api/v1/sandboxes/75496b3f-6ec0-46dd-9c7e-480d6c201a0d/properties/e7b77afe-271b-4159-bdd1-c312ef560cdb/rules"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002"
        },
        "rotateJWT": {
            "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/rotateJWT"
        },
        "clone": {
            "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/clone"
        }
    }
}
Parameter Description
Response Header parameters
X-Limit-Sandboxes-Limit Number of sandboxes allowed for your account.
X-Limit-Sandboxes-Remaining Number of sandboxes available to create in your account.
Location: Link to sandbox details for the sandbox you just created.
Response Body parameters
sandboxId The unique identifier for the sandbox.
createdBy The identifier for the developer who created the sandbox.
createdOn A timestamp representing when the system created the sandbox.
name The name of the sandbox defined by the developer when the sandbox was created. If you do not specify a name, the name will default to the sandboxId.
isClonable Indicates whether the sandbox can be copied for another developer’s use.
status
properties A list of the properties available for testing in the sandbox environment. A sandbox can contain more than one property.
sandboxPropertyId
requestHostnames A set of hostnames for use in testing within a developer’s sandbox.
_links HAL-formatted hypermedia links relating to the sandbox. See Hypermedia for more information.

Get a sandbox

Get a specific sandbox based on sandboxId.

GET /sandbox-api/v1/sandboxes/{sandboxId}

Sample: /sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007

Parameter Type Sample Description
URL parameters
sandboxId String e43a53d6-7430-11e8-8f80-0242ac110007 Unique identifier for the sandbox.

Status 200 application/json

Object type: Sandbox

Download schema: Sandbox.json

Response Body:

{
    "sandboxId": "2956607f-854e-11e8-898a-0242ac110002",
    "createdBy": "sandbox@akamai.com",
    "createdOn": "2018-07-11T21:05:38.227Z",
    "name": "Sandbox-clone-1",
    "isClonable": true,
    "status": "OK",
    "properties": [
        {
            "requestHostnames": [
                "shop.example.com"
            ],
            "_links": {
                "property": {
                    "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/properties/29b5e5a0-854e-11e8-898a-0242ac110002"
                },
                "rules": {
                    "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/properties/29b5e5a0-854e-11e8-898a-0242ac110002/rules"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002"
        },
        "rotateJWT": {
            "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/rotateJWT"
        },
        "clone": {
            "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/clone"
        }
    }
}
  1. Run the List sandboxes operation to see the sandboxes you created.

  2. Choose a sandboxId from within the sandboxes array in the response object.

  3. Make a GET request to /sandbox-api/v1/sandboxes/{sandboxId}.

  4. Alternatively, locate the link entitled self in the response object of the List sandboxes operation and GET the associated href.

Modify a sandbox

Enable isClonable if you have preconfigured the settings for the sandbox and want to make it readily available to other developers in your organization. You can also update the sandbox name to make it easily identifiable in the response object.

PUT /sandbox-api/v1/sandboxes/{sandboxId}

Sample: /sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007

Content-Type: application/json

Object type: Sandbox

Download schema: Sandbox.json

Request Body:

{
    "sandboxId": "13b8614c-6fe3-11e8-a4d6-0242ac110002",
    "createdBy": "devops-99@example.com",
    "createdOn": "2018-06-14T14:56:11.391Z",
    "name": "SHOP-123212",
    "isClonable": true,
    "properties": [
        {
            "requestHostnames": [
                "foo.example.com",
                "info.example.com",
                "shop.example.com"
            ]
        }
    ]
}
Parameter Type Sample Description
URL parameters
sandboxId String e43a53d6-7430-11e8-8f80-0242ac110007 Unique identifier for the sandbox.

Status 204

  1. Run the List sandboxes operation to see the sandboxes you created.

  2. Choose a sandboxId from within the sandboxes array in the response object and run the Get a sandbox operation.

  3. Modify the JSON object with the Sandbox members you want to include. For example: specify a new name for the sandbox and enable isClonable so other developers can clone this preconfigured sandbox for their own use.

  4. Make a PUT request to /sandbox-api/v1/sandboxes/{sandboxId}.

Delete a sandbox

Remove a specific sandbox instance based on sandboxId. This is useful when you have completed testing and no longer need the sandbox, or when you are approaching the 100 sandboxes limit.

DELETE /sandbox-api/v1/sandboxes/{sandboxId}

Sample: /sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007

Parameter Type Sample Description
URL parameters
sandboxId String e43a53d6-7430-11e8-8f80-0242ac110007 Unique identifier for the sandbox.

Status 204

  1. Run the List sandboxes operation to see the sandboxes you created.

  2. Choose a sandboxId from within the sandboxes array in the response object.

  3. Make a DELETE request to /sandbox-api/v1/sandboxes/{sandboxId}.

Rotate the JWT

Generate a new jwtToken (JSON Web Token) for the specified sandbox instance. Use this to prevent access to a particular sandbox by developers who had the previous JWT.

POST /sandbox-api/v1/sandboxes/{sandboxId}/rotateJWT

Sample: /sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/rotateJWT

Parameter Type Sample Description
URL parameters
sandboxId String e43a53d6-7430-11e8-8f80-0242ac110007 Unique identifier for the sandbox.

Status 200 application/json

Download schema: PostRotateResponse.json

Response Body:

{
    "jwtToken": "eyJ0eXAiOiJKV1QiLC...NwpuL1f8z9U6Se3p_uYa_sgfWzw"
}
  1. Run the List sandboxes operation to see the sandboxes you created.

  2. Choose a sandboxId from within the sandboxes array in the response object.

  3. Make a POST request to /sandbox-api/v1/sandboxes/{sandboxId}/rotateJWT.

  4. Copy the jwtToken from the response object.

    NOTE: This is the only time you will see the jwtToken other than when you Create a sandbox.

  5. Modify the config.json file (generated by the Sandbox Client). Refer to the User Guide for instructions.

Clone a sandbox

Create a new sandbox instance based on the specified sandboxId. You can clone a sandbox that has isClonable enabled. This is useful if you want to copy a sandbox that was preconfigured by another developer within your organization. Keep in mind that this is the only way to create a sandbox if you do not have authorization for Property Manager enabled in Control Center.

POST /sandbox-api/v1/sandboxes/{sandboxId}/clone

Sample: /sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/clone

Content-Type: application/json

Object type: CloneSandbox

Download schema: PostCloneRequest.json

Request Body:

{
    "name": "sandbox-clone-1"
}
Parameter Type Sample Description
URL parameters
sandboxId String e43a53d6-7430-11e8-8f80-0242ac110007 Unique identifier for the sandbox.

Status 200 application/json

Headers:

X-Limit-Sandboxes-Limit: 100
X-Limit-Sandboxes-Remaining: 98
Location: /sandbox-api/v1/sandboxes/7ccfb989-68ce-11e8-bdfe-0242ac110002

Response Body:

{
    "sandboxId": "2956607f-854e-11e8-898a-0242ac110002",
    "createdBy": "joe@example.com",
    "createdOn": "2018-10-09T15:20:36.441Z",
    "name": "Sandbox-123",
    "jwtToken": "eyJ0eXA ... qggqqw",
    "isClonable": true,
    "status": "OK",
    "properties": [
        {
            "sandboxPropertyId": "e7b77afe-271b-4159-bdd1-c312ef560cdb",
            "requestHostnames": [
                "foo.exampledevops.com",
                "foobar.abc1234def.com"
            ],
            "additionalRequestHostnamesInProperty": [
                "www.abc1234def.com"
            ],
            "_links": {
                "property": {
                    "href": "/sandbox-api/v1/sandboxes/75496b3f-6ec0-46dd-9c7e-480d6c201a0d/properties/e7b77afe-271b-4159-bdd1-c312ef560cdb"
                },
                "rules": {
                    "href": "/sandbox-api/v1/sandboxes/75496b3f-6ec0-46dd-9c7e-480d6c201a0d/properties/e7b77afe-271b-4159-bdd1-c312ef560cdb/rules"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002"
        },
        "rotateJWT": {
            "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/rotateJWT"
        },
        "clone": {
            "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/clone"
        }
    }
}
  1. Run the List sandboxes operation, then choose a sandboxId from within the sandboxes array in the response object.

    NOTE: If you want to clone a sandbox that another developer created, ask the developer to give you the specific sandboxId.

  2. Form a CloneSandbox object to include a meaningful name for the sandbox. If you do not specify a name, the default name will be the sandboxId.

  3. Make a POST request to /sandbox-api/v1/sandboxes/{sandboxId}/clone to create a sandbox instance for your individual use with the same settings.

  4. Alternatively, locate the link entitled clone in the response object of the List sandboxes operation and GET the associated href.

List properties

This operation returns a list of sandbox properties available to the current user.

GET /sandbox-api/v1/sandboxes/{sandboxId}/properties

Sample: /sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties

Parameter Type Sample Description
URL parameters
sandboxId String e43a53d6-7430-11e8-8f80-0242ac110007 Unique identifier for the sandbox.

Status 200 application/json

Object type: Property

Download schema: Properties.json

Response Body:

{
    "properties": [
        {
            "sandboxPropertyId": "ad37282c-8549-11e8-898a-0242ac110002",
            "requestHostnames": [
                "foo.example.com"
            ],
            "additionalRequestHostnamesInProperty": [
                "portal.example.com"
            ],
            "propertyId": "prp_1712",
            "productId": "prd_Fresca",
            "cpcode": 725533,
            "ruleFormat": "latest",
            "validationStatus": "SUCCESS",
            "filteredRuleBehaviors": [
                "http2"
            ],
            "editedRuleBehaviors": [
                "cpCode"
            ],
            "_links": {
                "self": {
                    "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002"
                },
                "sandbox": {
                    "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002"
                },
                "rules": {
                    "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002/rules"
                }
            }
        }
    ]
}

Add a property to a sandbox

Add another property to the sandbox. Use this if you need to support more than one hostname in your sandbox environment.

POST /sandbox-api/v1/sandboxes/{sandboxId}/properties

Sample: /sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties

Content-Type: application/json

Object type: AddProperty

Download schema: PostPropertyFromRulesOrPropertyRequest.json

Request Body:

{
    "createFromProperty": {
        "propertyId": 470031
    },
    "requestHostnames": [
        "portal.example.com"
    ]
}
Parameter Type Sample Description
URL parameters
sandboxId String e43a53d6-7430-11e8-8f80-0242ac110007 Unique identifier for the sandbox.

Status 200 application/json

Headers:

Location: /sandbox-api/v1/sandboxes/7ccfb989-68ce-11e8-bdfe-0242ac110002/properties/f48caeff-68e5-11e8-8870-0242ac110003

Object type: Property

Download schema: Property.json

Response Body:

{
    "sandboxPropertyId": "e4ae2447-7430-11e8-8f80-0242ac110007",
    "requestHostnames": [
        "foo.example.com"
    ],
    "additionalRequestHostnamesInProperty": [
        "portal.example.com"
    ],
    "propertyId": 470031,
    "cpcode": 707514,
    "productId": "prd_Fresca",
    "ruleFormat": "latest",
    "validationStatus": "SUCCESS",
    "filteredRuleBehaviors": [
        "http2"
    ],
    "editedRuleBehaviors": [
        "cpCode"
    ],
    "_links": {
        "self": {
            "href": "/sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties/e4ae2447-7430-11e8-8f80-0242ac110007"
        },
        "rules": {
            "href": "/sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties/e4ae2447-7430-11e8-8f80-0242ac110007/rules"
        },
        "sandbox": {
            "href": "/sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007"
        }
    }
}
  1. Run the List sandboxes operation to see the sandboxes you created.

  2. Choose a sandboxId from within the sandboxes array in the response object.

  3. Modify the JSON request body with the requestHostnames you want to add to the sandbox.

  4. Make a POST request to /sandbox-api/v1/sandboxes/{sandboxId}/properties.

Read a property

Get a specific property of a sandbox so you can review the information in the response body.

GET /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}

Sample: /sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties/e4ae2447-7430-11e8-8f80-0242ac110007

Parameter Type Sample Description
URL parameters
sandboxId String e43a53d6-7430-11e8-8f80-0242ac110007 Unique identifier for the sandbox.
sandboxPropertyId String e4ae2447-7430-11e8-8f80-0242ac110007 Unique identifier for the property within a sandbox.

Status 200 application/json

Object type: Property

Download schema: Property.json

Response Body:

{
    "sandboxPropertyId": "ad37282c-8549-11e8-898a-0242ac110002",
    "requestHostnames": [
        "foo.example.com"
    ],
    "additionalRequestHostnamesInProperty": [
        "portal.example.com"
    ],
    "propertyId": "prp_1712",
    "productId": "prd_Fresca",
    "cpcode": 725533,
    "ruleFormat": "latest",
    "validationStatus": "SUCCESS",
    "filteredRuleBehaviors": [
        "http2"
    ],
    "editedRuleBehaviors": [
        "cpCode"
    ],
    "_links": {
        "self": {
            "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002"
        },
        "sandbox": {
            "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002"
        },
        "rules": {
            "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002/rules"
        }
    }
}
  1. Run the List sandboxes operation to see the sandboxes you created.

  2. Choose a sandboxId from within the sandboxes array in the response object and run the Get a sandbox operation.

  3. Choose a sandboxPropertyId from the Property response object.

  4. Make a GET request to /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}.

Update a property

Update the requestHostnames of the sandbox property.

PUT /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}

Sample: /sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties/e4ae2447-7430-11e8-8f80-0242ac110007

Content-Type: application/json

Object type: Property

Download schema: Property.json

Request Body:

{
    "sandboxPropertyId": "e4ae2447-7430-11e8-8f80-0242ac110007",
    "requestHostnames": [
        "portal2.example.com"
    ],
    "propertyId": 470031,
    "cpcode": 707514,
    "productId": "prd_Fresca",
    "_links": {
        "self": {
            "href": "/sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties/e4ae2447-7430-11e8-8f80-0242ac110007"
        },
        "sandbox": {
            "href": "/sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007"
        },
        "rules": {
            "href": "/sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties/e4ae2447-7430-11e8-8f80-0242ac110007/rules"
        }
    }
}
Parameter Type Sample Description
URL parameters
sandboxId String e43a53d6-7430-11e8-8f80-0242ac110007 Unique identifier for the sandbox.
sandboxPropertyId String e4ae2447-7430-11e8-8f80-0242ac110007 Unique identifier for the property within a sandbox.

Status 204

  1. Run the List sandboxes operation to see the sandboxes you created.

  2. Choose a sandboxId from within the sandboxes array in the response object and run the Get a sandbox operation.

  3. Choose a sandboxPropertyId from the from the Property response object.

  4. Modify the JSON request body with the AddProperty members you want to include.

  5. Make a PUT request to /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}.

Delete a property

Remove a property from a sandbox. This operation applies when the sandbox contains more than one property. You cannot delete the only property of a sandbox.

DELETE /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}

Sample: /sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties/e4ae2447-7430-11e8-8f80-0242ac110007

Parameter Type Sample Description
URL parameters
sandboxId String e43a53d6-7430-11e8-8f80-0242ac110007 Unique identifier for the sandbox.
sandboxPropertyId String e4ae2447-7430-11e8-8f80-0242ac110007 Unique identifier for the property within a sandbox.

Status 204

  1. Run the List sandboxes operation to see the sandboxes you created.

  2. Choose a sandboxId from within the sandboxes array in the response object and run the Get a sandbox operation.

  3. Choose a sandboxPropertyId from the Property response object.

  4. Make a DELETE request to /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}.

Get a rule tree

Get a specific rule tree of a sandbox property. Each sandbox property references one rule tree. For more information on how content-handling rules are defined, review the Property Manager API.

GET /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}/rules

Sample: /sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties/e4ae2447-7430-11e8-8f80-0242ac110007/rules

Parameter Type Sample Description
URL parameters
sandboxId String e43a53d6-7430-11e8-8f80-0242ac110007 Unique identifier for the sandbox.
sandboxPropertyId String e4ae2447-7430-11e8-8f80-0242ac110007 Unique identifier for the property within a sandbox.

Status 200 application/json

Object type: Rules

Download schema: Rules.json

Response Body:

{
    "rules": {
        "name": "default",
        "children": [
            {
                "name": "Handle /my-path",
                "criteriaMustSatisfy": "all",
                "criteria": [
                    {
                        "name": "path",
                        "value": [
                            "/my-path"
                        ]
                    }
                ],
                "behaviors": [
                    {
                        "name": "caching",
                        "behavior": "max-age",
                        "ttl": "1m"
                    }
                ]
            }
        ]
    },
    "_links": {
        "self": {
            "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002/rules"
        },
        "sandbox": {
            "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002"
        },
        "property": {
            "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002"
        }
    }
}
  1. Run the List sandboxes operation to see the sandboxes you created.

  2. Choose a sandboxId from within the sandboxes array in the response object and run the Get a sandbox operation.

  3. Choose a sandboxPropertyId from the Property response object.

  4. Make a GET request to /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}/rules.

Update a rule tree

Modify the Rules of a sandbox property to make changes to content-handling behaviors for testing purposes within your development environment. Once you are satisfied with the results in your sandbox, you can use the Property Manager API to apply the rule changes to your property configuration.

PUT /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}/rules

Sample: /sandbox-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties/e4ae2447-7430-11e8-8f80-0242ac110007/rules

Content-Type: application/json

Object type: Rules

Download schema: Rules.json

Request Body:

{
    "rules": {
        "name": "default",
        "children": [
            {
                "name": "Handle /my-path",
                "criteriaMustSatisfy": "all",
                "criteria": [
                    {
                        "name": "path",
                        "value": [
                            "/my-path"
                        ]
                    }
                ],
                "behaviors": [
                    {
                        "name": "caching",
                        "behavior": "max-age",
                        "ttl": "5m"
                    }
                ]
            }
        ]
    }
}
Parameter Type Sample Description
URL parameters
sandboxId String e43a53d6-7430-11e8-8f80-0242ac110007 Unique identifier for the sandbox.
sandboxPropertyId String e4ae2447-7430-11e8-8f80-0242ac110007 Unique identifier for the property within a sandbox.

Status 204

  1. Run the List sandboxes operation to see the sandboxes you created.

  2. Choose a sandboxId from within the sandboxes array in the response object and run the Get a sandbox operation.

  3. Choose a sandboxPropertyId from the Property response object, and run the Get a rule tree operation.

  4. Change the content-handling settings within the Rules object as desired for testing.

  5. Make a PUT request to /sandbox-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}/rules.

NOTE: The changes you apply to content-handling behaviors within the sandbox are for testing purposes.

Data

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

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.

Property

Each sandbox contains at least one property. The property configuration describes the origin location and content-handling specifications.

Download schema: Property.json

Sample GET response:

{
    "sandboxPropertyId": "ad37282c-8549-11e8-898a-0242ac110002",
    "requestHostnames": [
        "foo.example.com"
    ],
    "additionalRequestHostnamesInProperty": [
        "portal.example.com"
    ],
    "propertyId": "prp_1712",
    "productId": "prd_Fresca",
    "cpcode": 725533,
    "ruleFormat": "latest",
    "validationStatus": "SUCCESS",
    "filteredRuleBehaviors": [
        "http2"
    ],
    "editedRuleBehaviors": [
        "cpCode"
    ],
    "_links": {
        "self": {
            "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002"
        },
        "sandbox": {
            "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002"
        },
        "rules": {
            "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002/rules"
        }
    }
}

Property members

Member Type Required Description
Property: Each sandbox contains at least one property. The property configuration describes the origin location and content-handling specifications.
_links Object HAL-formatted hypermedia links relating to the property. See Hypermedia for more information.
additionalRequestHostnamesInProperty Array Additional customer-specific hostnames found in the property configuration that the sandbox was based on that were not specified in the createFromProperty request.
cpcode Number Read-only. Unique identifier used for reporting traffic served. The Sandbox API tries to use the same CP code for all traffic within a particular Control Center access group.
editedRuleBehaviors Array Behaviors in the rule tree that were modified for use in the Sandbox.
filteredRuleBehaviors Array Behaviors in the rule tree that were removed because they are not supported by Sandbox.
productId String Read-only. The specific Akamai product associated with the property, as defined in Property Manager.
propertyId String Read-only. The identifier for the property from which the sandbox was created if developer used createFromProperty option.
requestHostnames Array Customer-specific hostnames included in the property configuration that may be used to make requests and test changes in the sandbox. The Sandbox API will default to the hostnames configured in the property unless you specify an alternate in the request.
ruleFormat String Read-only. The specific Property Manager rule format that is used with the property.
sandboxPropertyId String Read-only. Unique identifier for a property within the sandbox.
validationStatus String Read-only. The validation status for the property. If the status is OK the sandbox can serve traffic. If the status is ERROR the sandbox create request may have included an invalid property.
validationWarnings Array Contains any warnings from validating the rule tree. This field is only present if there were warnings during creation of a sandbox or addition of a sandbox property.

CreateSandbox

You can create a sandbox from a property or from a rule tree. Create a JSON request including data members as described in the table below.

Download schema: PostSandboxFromRulesOrPropertyRequest.json

Sample POST request to create a sandbox:

{
    "createFromProperty": {
        "propertyName": "exampledevops.com",
        "propertyVersion": 12345
    },
    "name": "Sandbox-123",
    "isClonable": true
}

CreateSandbox members

Member Type Required Description
CreateSandbox: You can create a sandbox from a property or from a rule tree. Create a JSON request including data members as described in the table below.
contractId String The specific contract that should be used.
cpcode Number Reporting code to be used for the new sandbox. If you do not specify a name, the system will create one. Typically this value is not specified and sandboxes will use the system default so that sandbox traffic may be reported in isolation.
createFromProperty CreateSandbox.createFromProperty Specifies an identifier for the property to include in the sandbox. Mutually exclusive with createFromRules. Include one of the following: hostname, propertyName, propertyId, or edgeHostname in the request body.
createFromRules CreateSandbox.createFromRules Specifies the rule tree for the property to include in the sandbox. Mutually exclusive with createFromProperty. The content-handling rules are defined in the Property Manager API.
groupId String The specific group that should be used.
isClonable Boolean Indicates whether the sandbox can be cloned by other developers.
name String Descriptive name for the new sandbox. If you do not specify a name, the default name will be the sandboxId. You will get an error message if the name is not unique.
requestHostnames Array Specifies the hostnames for the request. Use this option with createFromRules. If you try to createFromProperty with a requestHostname that is not already contained in the property configuration, you may get unexpected results. The Sandbox API automatically converts any specified request hostnames to lower case.
CreateSandbox.createFromProperty: Specifies an identifier for the property to include in the sandbox. Mutually exclusive with createFromRules. Include one of the following: hostname, propertyName, propertyId, or edgeHostname in the request body.
edgeHostname String The edge hostname associated with the property as configured in Property Manager.
hostname String The hostname associated with the property as configured in Property Manager. Use this option only of there is a one-to-one correspondence between the hostname and property. This method will fail if more than one property reference the same hostname.
propertyId Number The unique identifier for the property as it appears in Property Manager.
propertyName String The name of the property as it appears in Property Manager.
propertyVersion Number Include the version number with any of the other criteria. If not specified, the API will use the version that is active in production. If no such version is found, the call will fail.
CreateSandbox.createFromRules: Specifies the rule tree for the property to include in the sandbox. Mutually exclusive with createFromProperty. The content-handling rules are defined in the Property Manager API.
rules Object Defines how your website and applications process requests and the behaviors to apply to those requests.

CloneSandbox

You can clone a sandbox based on a preconfigured sandbox if you have the sandboxId.

Download schema: PostCloneRequest.json

Sample POST request to clone a sandbox:

{
    "name": "sandbox-clone-1"
}

CloneSandbox members

Member Type Required Description
CloneSandbox: You can clone a sandbox based on a preconfigured sandbox if you have the sandboxId.
name String Descriptive name for the new sandbox.

AddProperty

You can include more than one property within a sandbox.

Download schema: PostPropertyFromRulesOrPropertyRequest.json

Sample POST request to create a property:

{
    "createFromProperty": {
        "propertyId": 470031
    },
    "requestHostnames": [
        "portal.example.com"
    ]
}

AddProperty members

Member Type Required Description
AddProperty: You can include more than one property within a sandbox.
contractId String The identifier you can use to create a sandbox based on a specific contract.
cpcode Number Unique code that enables you to isolate sandbox traffic in report data. If you do not specify a number, the system will generate one.
createFromProperty AddProperty.createFromProperty Specifies an identifier for the property to include in the sandbox. Mutually exclusive with createFromRules. Include one of the following: propertyId, propertyName, hostname or edgeHostname in the request body.
createFromRules AddProperty.createFromRules Specifies the rule tree for the property to include in the sandbox. Mutually exclusive with createFromProperty. The content-handling rules are defined in the Property Manager API.
groupId String The identifier you can use to create a sandbox based on a specific group.
requestHostnames Array Specifies the hostnames for the request. Use this option with createFromRules. If you try to createFromProperty with a requestHostname that is not already contained in the property configuration, you may get unexpected results. The Sandbox API automatically converts any specified request hostnames to lower case.
AddProperty.createFromProperty: Specifies an identifier for the property to include in the sandbox. Mutually exclusive with createFromRules. Include one of the following: propertyId, propertyName, hostname or edgeHostname in the request body.
edgeHostname String The edge hostname associated with the property as configured in Property Manager.
hostname String The hostname associated with the property as configured in Property Manager. Use this option only if there is a one-to-one correspondence between the hostname and property. This method will fail if more than one property reference the same hostname.
propertyId Number The unique identifier for the property as it appears in Property Manager.
propertyName String The name of the property as it appears in Property Manager.
propertyVersion Number Include the version number with any of the other criteria. If not specified, the API will use the version that is active in production. If no such version is found, the call will fail.
AddProperty.createFromRules: Specifies the rule tree for the property to include in the sandbox. Mutually exclusive with createFromProperty. The content-handling rules are defined in the Property Manager API.
rules Object Defines how your website and applications process requests and the behaviors to apply to those requests.

Rules

Each sandbox property references one rule tree.

Download schema: Rules.json

Sample GET response:

{
    "rules": {
        "name": "default",
        "children": [
            {
                "name": "Handle /my-path",
                "criteriaMustSatisfy": "all",
                "criteria": [
                    {
                        "name": "path",
                        "value": [
                            "/my-path"
                        ]
                    }
                ],
                "behaviors": [
                    {
                        "name": "caching",
                        "behavior": "max-age",
                        "ttl": "1m"
                    }
                ]
            }
        ]
    },
    "_links": {
        "self": {
            "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002/rules"
        },
        "sandbox": {
            "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002"
        },
        "property": {
            "href": "/sandbox-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002"
        }
    }
}

Rules members

Member Type Required Description
Rules: Each sandbox property references one rule tree.
_links Object HAL-formatted hypermedia links relating to the rule tree. See Hypermedia for more information.
rules Object Specifies the rule tree for this sandbox property. The content-handling rules are defined in the Property Manager API.

Sandbox

A sandbox is an isolated development environment used for testing. Each sandbox has a unique identifier, or sandboxId. If you create a sandbox with isClonable enabled, another developer can quickly create a sandbox with the same configuration settings. When you create a sandbox, give it a meaningful name.

Download schema: Sandbox.json

Sample GET response:

{
    "sandboxId": "2956607f-854e-11e8-898a-0242ac110002",
    "createdBy": "sandbox@akamai.com",
    "createdOn": "2018-07-11T21:05:38.227Z",
    "name": "Sandbox-clone-1",
    "isClonable": true,
    "status": "OK",
    "properties": [
        {
            "requestHostnames": [
                "shop.example.com"
            ],
            "_links": {
                "property": {
                    "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/properties/29b5e5a0-854e-11e8-898a-0242ac110002"
                },
                "rules": {
                    "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/properties/29b5e5a0-854e-11e8-898a-0242ac110002/rules"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002"
        },
        "rotateJWT": {
            "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/rotateJWT"
        },
        "clone": {
            "href": "/sandbox-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/clone"
        }
    }
}

Sandbox members

Member Type Required Description
Sandbox: A sandbox is an isolated development environment used for testing. Each sandbox has a unique identifier, or sandboxId. If you create a sandbox with isClonable enabled, another developer can quickly create a sandbox with the same configuration settings. When you create a sandbox, give it a meaningful name.
_links Object HAL-formatted hypermedia links relating to the sandbox. See Hypermedia for more information.
createdBy String Read-only. The identifier for the developer who created the sandbox.
createdOn String Read-only. A timestamp representing when the system created the sandbox.
isClonable Boolean Indicates whether the sandbox can be copied for another developer’s use.
jwtToken String Java Web Token that is returned in the JSON response when you create a sandbox and is used for authentication. You need this string value to configure the Sandbox Client.
name String The name of the sandbox defined by the developer when the sandbox was created. If you do not specify a name, the name will default to the sandboxId.
properties Sandbox.properties[] A list of the properties available for testing in the sandbox environment. A sandbox can contain more than one property, but a given hostname may only be associated to one property within a sandbox.
sandboxId String Read-only. The unique identifier for the sandbox.
status String Read-only. The status of the sandbox. OK indicates that the sandbox is able to send traffic.
Sandbox.properties[]: A list of the properties available for testing in the sandbox environment. A sandbox can contain more than one property, but a given hostname may only be associated to one property within a sandbox.
_links Object HAL-formatted hypermedia links relating to the sandbox’s properties. See Hypermedia for more information.
additionalRequestHostnamesInProperty Array A set of hostnames that are associated with the property on which this sandbox was based but were not included as request hostnames in the POST. This list is only returned when you use the createFromProperty method.
requestHostnames Array A set of hostnames you can use for testing requests within your sandbox.
sandboxPropertyId String Read-only. The unique identifier for the sandbox.

Errors

This section provides details on the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

This API adheres to the Problem Details for HTTP APIs standard and returns detailed error responses, such as:

{
    "type": "/sandbox-api/error-types/property-manager-search-failed",
    "title": "We were unable to find the specified Property.",
    "detail": "No match found for search 'PropertyId=123'",
    "instance": "/sandbox-api/error-instances/d26808a4-fd0f-411c-801f-ab20ee4f455a",
    "status": 400,
}

HTTP status codes

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

Code Description
200 The operation was successful.
204 Successfully processed request.
400 Bad Request.
403 Access is forbidden.
404 Resource not found.
409 Conflict with current state of resource.
415 Unsupported media type.
500 Internal server error.

Last modified: 1/15/2019