DevPoPs 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

Use the DevPoPs API to create a sandbox, an isolated environment for testing site changes or Akamai property configurations locally before deploying. Incorporate the DevPoPs 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 pre-configured by another developer within your Luna group.

Who should use this API

Resolving issues with your website and applications after a property configuration is pushed to the content delivery network is inefficient and a drain on resources. With DevPoPs, each developer can test site and Akamai property changes within an isolated sandbox environment to identify issues locally before merging. This accelerates the development process and improves efficiency.

Getting started

  1. Create an API client in Luna for the DevPoPs API with READ-WRITE access. Follow the steps in Get Started with APIs to learn how to configure credentials to access the API.

    NOTE: In order to use the Create a sandbox operation, you must have authorization for Property Manager enabled in Luna. If you do not have authorization for Property Manager configured in Luna, you can only create a sandbox with the Clone a sandbox operation.

  2. Download and configure the DevPoPs Client, a proxy server that routes bidirectional requests between your development machine and the Akamai network via a secure gateway. Follow the Get Started with DevPoPs instructions to set up your sandbox.

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": "/devpops-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002/rules"
    },
    "sandbox": {
        "href": "/devpops-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002"
    },
    "property": {
        "href": "/devpops-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 Luna 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 DevPoPs 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 Luna, you can only create a sandbox with the Clone a sandbox operation.

The following summarizes the resources available in the DevPoPs 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 DevPoPs 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 /devpops-api/v1/sandboxes
Create a sandbox POST /devpops-api/v1/sandboxes
Get a sandbox GET /devpops-api/v1/sandboxes/{sandboxId}
Modify a sandbox PUT /devpops-api/v1/sandboxes/{sandboxId}
Delete a sandbox DELETE /devpops-api/v1/sandboxes/{sandboxId}
Rotate the JWT POST /devpops-api/v1/sandboxes/{sandboxId}/rotateJWT
Clone a sandbox POST /devpops-api/v1/sandboxes/{sandboxId}/clone
Add a property to a sandbox POST /devpops-api/v1/sandboxes/{sandboxId}/properties
Read a property GET /devpops-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}
Update a property PUT /devpops-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}
Delete a property DELETE /devpops-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}
Get a rule tree GET /devpops-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}/rules
Update a rule tree PUT /devpops-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 /devpops-api/v1/sandboxes

Status 200 application/json

Headers:

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

Response Body:

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

Create a sandbox

This operation creates a new sandbox instance in one of two ways: Create a sandbox from a property or Create a sandbox from a rule tree. Form a JSON request according to the CreateSandbox schema. You must have an API client for the DevPoPs API with READ-WRITE access, and Property Manager authorization enabled in Luna to create a sandbox with this method.

POST /devpops-api/v1/sandboxes

Content-Type: application/json

Request Body:

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

Status 200 application/json

Headers:

X-Limit-Sandboxes-Limit: 100
X-Limit-Sandboxes-Remaining: 98
Location: /devpops-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": "/devpops-api/v1/sandboxes/75496b3f-6ec0-46dd-9c7e-480d6c201a0d/properties/e7b77afe-271b-4159-bdd1-c312ef560cdb"
                },
                "rules": {
                    "href": "/devpops-api/v1/sandboxes/75496b3f-6ec0-46dd-9c7e-480d6c201a0d/properties/e7b77afe-271b-4159-bdd1-c312ef560cdb/rules"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "/devpops-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002"
        },
        "rotateJWT": {
            "href": "/devpops-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/rotateJWT"
        },
        "clone": {
            "href": "/devpops-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/clone"
        }
    }
}

Create a sandbox from a property

  1. Form a JSON request body with one of the following data members:
    • hostname: recommended if there is a one-to-one correspondence between the hostname and property.

    • propertyName: as defined in Property Manager; this is recommended if you have more than one property configuration that references the same hostname.

    • propertyId: you can find this value with the Property Manager API.

    • edgeHostname: you can find this value in Property Manager.

  2. Include propertyVersion with any of the above to specify which version of the property configuration to include in your sandbox.

    Example createFromProperty JSON request body:

    {
    "createFromProperty": {
        "hostname": "www.devopsexample.com",
        "propertyVersion": 78910
    },
    "name": "Sandbox-321",
    "isClonable": true
    }
    
  3. Make a POST request to /devpops-api/v1/sandboxes.

  4. Copy the jwtToken in the response object. You need this to configure your DevPoPs Client. Refer to Get Started with DevPoPs for instructions.

Create a sandbox from a rule tree

  1. Form a JSON request body that references a rule tree and include one or more requestHostnames.

    Example createFromRules JSON request body:

    {
      "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": [
      ]
    }
      }
    }
    
  2. Make a POST request to /devpops-api/v1/sandboxes.

  3. Copy the jwtToken in the response object. You need this to configure your DevPoPs Client. Refer to Get Started with DevPoPs for instructions.

Get a sandbox

Get a specific sandbox based on sandboxId.

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

Sample: /devpops-api/v1/sandboxes/7ccfb989-68ce–11e8-bdfe–0242ac110002

Parameter Type Sample Description
URL parameters
sandboxId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 Unique identifier for the sandbox.

Status 200 application/json

Response Body:

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

Sample: /devpops-api/v1/sandboxes/7ccfb989-68ce–11e8-bdfe–0242ac110002

Content-Type: application/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 7ccfb989-68ce-11e8-bdfe-0242ac110002 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 pre-configured sandbox for their own use.

  4. Make a PUT request to /devpops-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 /devpops-api/v1/sandboxes/{sandboxId}

Sample: /devpops-api/v1/sandboxes/7ccfb989-68ce–11e8-bdfe–0242ac110002

Parameter Type Sample Description
URL parameters
sandboxId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 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 /devpops-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 /devpops-api/v1/sandboxes/{sandboxId}/rotateJWT

Sample: /devpops-api/v1/sandboxes/7ccfb989-68ce–11e8-bdfe–0242ac110002/rotateJWT

Parameter Type Sample Description
URL parameters
sandboxId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 Unique identifier for the sandbox.

Status 200 application/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 /devpops-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 DevPoPs Client). Refer to Get Started with DevPoPs 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 pre-configured by another developer within your organization. This is the only way to create a sandbox if you do not have authorization for Property Manager enabled in Luna.

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

Sample: /devpops-api/v1/sandboxes/7ccfb989-68ce–11e8-bdfe–0242ac110002/clone

Content-Type: application/json

Request Body:

{
    "name": "devpops-clone-1"
}
Parameter Type Sample Description
URL parameters
sandboxId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 Unique identifier for the sandbox.

Status 200 application/json

Headers:

X-Limit-Sandboxes-Limit: 100
X-Limit-Sandboxes-Remaining: 98
Location: /devpops-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": "/devpops-api/v1/sandboxes/75496b3f-6ec0-46dd-9c7e-480d6c201a0d/properties/e7b77afe-271b-4159-bdd1-c312ef560cdb"
                },
                "rules": {
                    "href": "/devpops-api/v1/sandboxes/75496b3f-6ec0-46dd-9c7e-480d6c201a0d/properties/e7b77afe-271b-4159-bdd1-c312ef560cdb/rules"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "/devpops-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002"
        },
        "rotateJWT": {
            "href": "/devpops-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/rotateJWT"
        },
        "clone": {
            "href": "/devpops-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 /devpops-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.

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 /devpops-api/v1/sandboxes/{sandboxId}/properties

Sample: /devpops-api/v1/sandboxes/7ccfb989-68ce–11e8-bdfe–0242ac110002/properties

Content-Type: application/json

Request Body:

{
    "createFromProperty": {
        "propertyId": 470031
    },
    "requestHostnames": [
        "portal.example.com"
    ]
}
Parameter Type Sample Description
URL parameters
sandboxId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 Unique identifier for the sandbox.

Status 200 application/json

Headers:

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

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": "/devpops-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties/e4ae2447-7430-11e8-8f80-0242ac110007"
        },
        "rules": {
            "href": "/devpops-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties/e4ae2447-7430-11e8-8f80-0242ac110007/rules"
        },
        "sandbox": {
            "href": "/devpops-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 /devpops-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 /devpops-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}

Sample: /devpops-api/v1/sandboxes/7ccfb989-68ce–11e8-bdfe–0242ac110002/properties/7ccfb989-68ce–11e8-bdfe–0242ac110002

Parameter Type Sample Description
URL parameters
sandboxId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 Unique identifier for the sandbox.
sandboxPropertyId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 Unique identifier for the property within a sandbox.

Status 200 application/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": "/devpops-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002"
        },
        "sandbox": {
            "href": "/devpops-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002"
        },
        "rules": {
            "href": "/devpops-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 /devpops-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}.

Update a property

Update the requestHostnames of the sandbox property.

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

Sample: /devpops-api/v1/sandboxes/7ccfb989-68ce–11e8-bdfe–0242ac110002/properties/7ccfb989-68ce–11e8-bdfe–0242ac110002

Content-Type: application/json

Request Body:

{
    "sandboxPropertyId": "e4ae2447-7430-11e8-8f80-0242ac110007",
    "requestHostnames": [
        "portal2.example.com"
    ],
    "propertyId": 470031,
    "cpcode": 707514,
    "productId": "prd_Fresca",
    "_links": {
        "self": {
            "href": "/devpops-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties/e4ae2447-7430-11e8-8f80-0242ac110007"
        },
        "sandbox": {
            "href": "/devpops-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007"
        },
        "rules": {
            "href": "/devpops-api/v1/sandboxes/e43a53d6-7430-11e8-8f80-0242ac110007/properties/e4ae2447-7430-11e8-8f80-0242ac110007/rules"
        }
    }
}
Parameter Type Sample Description
URL parameters
sandboxId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 Unique identifier for the sandbox.
sandboxPropertyId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 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 /devpops-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 /devpops-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}

Sample: /devpops-api/v1/sandboxes/7ccfb989-68ce–11e8-bdfe–0242ac110002/properties/7ccfb989-68ce–11e8-bdfe–0242ac110002

Parameter Type Sample Description
URL parameters
sandboxId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 Unique identifier for the sandbox.
sandboxPropertyId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 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 /devpops-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}.

Get a rule tree

Gets 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 /devpops-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}/rules

Sample: /devpops-api/v1/sandboxes/7ccfb989-68ce–11e8-bdfe–0242ac110002/properties/7ccfb989-68ce–11e8-bdfe–0242ac110002/rules

Parameter Type Sample Description
URL parameters
sandboxId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 Unique identifier for the sandbox.
sandboxPropertyId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 Unique identifier for the property within a sandbox.

Status 200 application/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": "/devpops-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002/rules"
        },
        "sandbox": {
            "href": "/devpops-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002"
        },
        "property": {
            "href": "/devpops-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 /devpops-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 /devpops-api/v1/sandboxes/{sandboxId}/properties/{sandboxPropertyId}/rules

Sample: /devpops-api/v1/sandboxes/7ccfb989-68ce–11e8-bdfe–0242ac110002/properties/7ccfb989-68ce–11e8-bdfe–0242ac110002/rules

Content-Type: application/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 7ccfb989-68ce-11e8-bdfe-0242ac110002 Unique identifier for the sandbox.
sandboxPropertyId String 7ccfb989-68ce-11e8-bdfe-0242ac110002 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 /devpops-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": "/devpops-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002"
        },
        "sandbox": {
            "href": "/devpops-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002"
        },
        "rules": {
            "href": "/devpops-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002/rules"
        }
    }
}

Property members

Member Type Required Description
_links Object HAL-formatted hypermedia links relating to the property. See Hypermedia for more information.
cpcode Number Read-only. Unique identifier used for reporting traffic served. DevPoPs tries to use the same CP code for all traffic within a particular Luna access group.
productId String Read-only. The specific Akamai product associated with the property, as defined in Property Manager.
propertyId String The identifier for the property from which the sandbox was created if developer used createFromProperty option.
requestHostnames Array Customer-specific hostnames defined in the Property Manager configuration. DevPoPs will default to the hostnames of the property, unless an alternate is specified in the request.
sandboxPropertyId String Read-only. Identifies a property within the sandbox.

CreateSandbox

You can create a sandbox from a property or from a rule tree. Create a JSON request body 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
createFromProperty CreateSandbox.createFromProperty 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.
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. DevPoPs will automatically convert any specified request hostnames to lower case.
CreateSandbox.createFromProperty: Specifies an identifier for the property to include in the sandbox. Mutually exclusive with createFromRules.
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.

CloneSandbox

You can clone a sandbox based on a pre-configured sandbox.

Download schema: PostCloneRequest.json

Sample POST request to clone a sandbox:

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

CloneSandbox members

Member Type Required Description
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
createFromProperty AddProperty.createFromProperty 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.
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. DevPoPs will automatically convert any specified request hostnames to lower case.
AddProperty.createFromProperty: Specifies an identifier for the property to include in the sandbox. Mutually exclusive with createFromRules.
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.

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": "/devpops-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002/rules"
        },
        "sandbox": {
            "href": "/devpops-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002"
        },
        "property": {
            "href": "/devpops-api/v1/sandboxes/ac6ef62b-8549-11e8-898a-0242ac110002/properties/ad37282c-8549-11e8-898a-0242ac110002"
        }
    }
}

Rules members

Member Type Required Description
_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": "devpops@akamai.com",
    "createdOn": "2018-07-11T21:05:38.227Z",
    "name": "DEVPOPS-clone-1",
    "isClonable": true,
    "status": "OK",
    "properties": [
        {
            "requestHostnames": [
                "shop.example.com"
            ],
            "_links": {
                "property": {
                    "href": "/devpops-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/properties/29b5e5a0-854e-11e8-898a-0242ac110002"
                },
                "rules": {
                    "href": "/devpops-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/properties/29b5e5a0-854e-11e8-898a-0242ac110002/rules"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "/devpops-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002"
        },
        "rotateJWT": {
            "href": "/devpops-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/rotateJWT"
        },
        "clone": {
            "href": "/devpops-api/v1/sandboxes/2956607f-854e-11e8-898a-0242ac110002/clone"
        }
    }
}

Sandbox members

Member Type Required Description
_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.
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 Read-only. A list of the properties available for testing in the sandbox environment. A sandbox can contain more than one property.
sandboxId String Read-only. The unique identifier for the sandbox.
Sandbox.properties: A list of the properties available for testing in the sandbox environment. A sandbox can contain more than one property.
_links Object HAL-formatted hypermedia links relating to the sandbox’s properties. See Hypermedia for more information.
requestHostnames Array A set of hostnames for use in testing within a developer’s 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": "/devpops-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": "/devpops-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: 10/12/2018