Aura LCDN Deployment API v1

Deploy and manage service instances of the LCDN product on the Aura platform.

Learn more:


Overview

This API allows the Licensed CDN (LCDN) Operator to deploy and manage service instances for the LCDN product on the Aura platform.

Get started

Before you use the Aura LCDN Deployment API for the first time, you must get an authorization token by creating and registering an application using the Aura Management Center (AMC) GUI. For detailed information about obtaining a token, see the “Managing OAuth2 Applications” section in the latest version of the Aura LCDN/LMS Administration Guide on the Aura LCDN and LMS product page on Akamai Control Center.

Resources

This section provides details about the Aura LCDN Deployment API’s various resources.

  • HyperCacheInstance: An instantiation of a HyperCache service on an LCDN node.

  • RequestRouterInstance: An instantiation of a Request Router service on an LCDN node.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
RequestRouter Instances  
List Request Router instances GET /api/lcdn-deployment/v1/request-router/instances
Create or update a Request Router instance PUT /api/lcdn-deployment/v1/request-router/instances/{nodeId}
Remove a Request Router instance DELETE /api/lcdn-deployment/v1/request-router/instances/{nodeId}
Get a Request Router instance GET /api/lcdn-deployment/v1/request-router/instances/{nodeId}
HyperCache Instances  
List HyperCache instances GET /api/lcdn-deployment/v1/hypercache/instances
Create or update a HyperCache instance PUT /api/lcdn-deployment/v1/hypercache/instances/{nodeId}
Remove a HyperCache instance DELETE /api/lcdn-deployment/v1/hypercache/instances/{nodeId}
Get a HyperCache instance GET /api/lcdn-deployment/v1/hypercache/instances/{nodeId}

List request routers

This operation returns a list of all instances configured on Request Router.

GET /api/lcdn-deployment/v1/request-router/instances

Status 200 application/json

Object type: RequestRouterInstance

Download schema: requestrouter-instance.collection.schema.json

Response body:

{
    "instances": [
        {
            "nodeId": 1,
            "hostname": "dut1.qa.lab.westford.akamai.com"
        }
    ],
    "page": {
        "pageNumber": 1,
        "pageSize": 100,
        "totalPages": 1,
        "totalResults": 1
    }
}
  1. Use the pageSize and pageNumber query parameters to control the set of data that gets returned.

  2. Optionally specify the view query parameter with a value of detailed to request the full details of each object within the collection.

  3. Make a GET request to /api/lcdn-deployment/v1/request-router/instances.

  4. The operation responds with a paged collection of RequestRouterInstance.

Create or update a request router

This operation deploys a new Request Router instance, or updates the details of an existing Request Router instance.

PUT /api/lcdn-deployment/v1/request-router/instances/{nodeId}

Sample: /api/lcdn-deployment/v1/request-router/instances/1

Content-Type: application/json

Object type: RequestRouterInstance

Download schema: requestrouter-instance.update.schema.json

Request body:

{
    "nodeId": 1,
    "serviceLabels": {
        "clientServing": [
            "172.25.138.202"
        ]
    }
}
Parameter Type Sample Description
URL path parameters
nodeId Integer 1 Uniquely identifies a RequestRouter instance.

Status 200 application/json

Object type: RequestRouterInstance

Download schema: requestrouter-instance.read-detailed.schema.json

Response body:

{
    "nodeId": 1,
    "hostname": "dut1.qa.lab.westford.akamai.com",
    "serviceLabels": {
        "clientServing": [
            "172.25.138.202"
        ]
    }
}

Status 201 application/json

Object type: RequestRouterInstance

Download schema: requestrouter-instance.read-detailed.schema.json

Response body:

{
    "nodeId": 1,
    "hostname": "dut1.qa.lab.westford.akamai.com",
    "serviceLabels": {
        "clientServing": [
            "172.25.138.202"
        ]
    }
}
  1. If the instance already exists, run the List Request Router instances operation to locate and store the current RequestRouterInstance object and nodeId.

  2. If this is for a new Request Router instance, use the Aura Infrastructure API’s List nodes operation to locate the nodeId of the target node.

  3. Update the RequestRouterInstance object, or create a new RequestRouterInstance object.

  4. PUT the RequestRouterInstance object to /api/lcdn-deployment/v1/request-router/instances/{nodeId}.

  5. The response reflects the RequestRouterInstance object that you updated or created.

Remove a request router

This operation deletes a Request Router instance.

DELETE /api/lcdn-deployment/v1/request-router/instances/{nodeId}

Sample: /api/lcdn-deployment/v1/request-router/instances/1

Parameter Type Sample Description
URL path parameters
nodeId Integer 1 Uniquely identifies a RequestRouter instance.

Status 204

  1. If you don’t have a nodeId value, run the List Request Router instances operation to locate the Request Router instance and store the nodeId value.

  2. Make a DELETE request to /api/lcdn-deployment/v1/request-router/instances/{nodeId}.

Get a request router

This operation retrieves the details of a Request Router instance.

GET /api/lcdn-deployment/v1/request-router/instances/{nodeId}

Sample: /api/lcdn-deployment/v1/request-router/instances/1

Parameter Type Sample Description
URL path parameters
nodeId Integer 1 Uniquely identifies a RequestRouter instance.

Status 200 application/json

Object type: RequestRouterInstance

Download schema: requestrouter-instance.read-detailed.schema.json

Response body:

{
    "nodeId": 1,
    "hostname": "dut1.qa.lab.westford.akamai.com",
    "serviceLabels": {
        "clientServing": [
            "172.25.138.202"
        ]
    }
}
  1. Run the List HyperCache instances operation to locate the nodeId of the target RequestRouterInstance object.

  2. Make a GET request to /api/lcdn-deployment/v1/request-router/instances.

  3. The operation responds with a RequestRouterInstance object.

List HyperCaches

This operation returns a list of all HyperCache instances configured on the LCDN.

GET /api/lcdn-deployment/v1/hypercache/instances

Status 200 application/json

Object type: HyperCacheInstance

Download schema: hypercache-instance.collection.schema.json

Response body:

{
    "instances": [
        {
            "nodeId": 3,
            "hostname": "dut3.primary.qa.lab.westford.akamai.com"
        }
    ],
    "page": {
        "pageNumber": 1,
        "pageSize": 100,
        "totalPages": 1,
        "totalResults": 1
    }
}
  1. Use the pageSize and pageNumber query parameters to control the set of data that gets returned.

  2. Optionally, specify the view query parameter with a value of detailed to request the full details of each object within the collection.

  3. Make a GET request to /api/lcdn-deployment/v1/hypercache/instances.

Create or update a HyperCache

This operation deploys a new HyperCache instance, or updates the details of an existing HyperCache instance.

PUT /api/lcdn-deployment/v1/hypercache/instances/{nodeId}

Sample: /api/lcdn-deployment/v1/hypercache/instances/1

Content-Type: application/json

Object type: HyperCacheInstance

Download schema: hypercache-instance.update.schema.json

Request body:

{
    "nodeId": 3,
    "license": "cookie=4b99e07285882cf4b2d00b73fdb57e6c expires on 12/2020\nLicense         2300044041085119055\nMachineID       8788515039232315429\n4b99e07285882cf4b2d00b73fdb57e6c 2300044041085119055 8788515039232315429\nCoGB 1024MB",
    "serviceLabels": {
        "intraSite": [
            "172.31.3.1"
        ],
        "interSite": [
            "172.31.3.1"
        ],
        "clientServing": [
            {
                "ipAddress": "172.25.138.204"
            }
        ]
    }
}
Parameter Type Sample Description
URL path parameters
nodeId Integer 1 Uniquely identifies a HyperCache instance.

Status 200 application/json

Object type: HyperCacheInstance

Download schema: hypercache-instance.read-detailed.schema.json

Response body:

{
    "nodeId": 3,
    "hostname": "dut3.primary.qa.lab.westford.akamai.com",
    "license": "cookie=4b99e07285882cf4b2d00b73fdb57e6c expires on 12/2020\nLicense         2300044041085119055\nMachineID       8788515039232315429\n4b99e07285882cf4b2d00b73fdb57e6c 2300044041085119055 8788515039232315429\nCoGB 1024MB",
    "serviceLabels": {
        "intraSite": [
            "172.31.3.1"
        ],
        "interSite": [
            "172.31.3.1"
        ],
        "clientServing": [
            {
                "ipAddress": "172.25.138.204"
            }
        ]
    }
}

Status 201 application/json

Object type: HyperCacheInstance

Download schema: hypercache-instance.read-detailed.schema.json

Response body:

{
    "nodeId": 3,
    "hostname": "dut3.primary.qa.lab.westford.akamai.com",
    "license": "cookie=4b99e07285882cf4b2d00b73fdb57e6c expires on 12/2020\nLicense         2300044041085119055\nMachineID       8788515039232315429\n4b99e07285882cf4b2d00b73fdb57e6c 2300044041085119055 8788515039232315429\nCoGB 1024MB",
    "serviceLabels": {
        "intraSite": [
            "172.31.3.1"
        ],
        "interSite": [
            "172.31.3.1"
        ],
        "clientServing": [
            {
                "ipAddress": "172.25.138.204"
            }
        ]
    }
}
  1. If the HyperCache instance already exists, run the List HyperCache instances operation to locate and store the current HyperCacheInstance object and nodeId.

  2. If this is for a new HyperCache instance, use the Aura Infrastructure API’s List nodes operation to locate the nodeId of the target node.

  3. Update the HyperCacheInstance object, or create a new HyperCacheInstance object.

  4. PUT the HyperCacheInstance object to /api/lcdn-deployment/v1/hypercache/instances/{nodeId}.

  5. The response reflects the HyperCacheInstance object that you updated or created.

Remove a HyperCache

This operation deletes a HyperCache instance.

DELETE /api/lcdn-deployment/v1/hypercache/instances/{nodeId}

Sample: /api/lcdn-deployment/v1/hypercache/instances/1

Parameter Type Sample Description
URL path parameters
nodeId Integer 1 Uniquely identifies a HyperCache instance.

Status 204

  1. If you don’t have a nodeId value, run the List HyperCache instances operation to locate the HyperCache instance and store the nodeId value.

  2. Make a DELETE request to /api/lcdn-deployment/v1/hypercache/instances/{nodeId}.

Get a HyperCache

This operation retrieves the details of a HyperCache instance.

GET /api/lcdn-deployment/v1/hypercache/instances/{nodeId}

Sample: /api/lcdn-deployment/v1/hypercache/instances/1

Parameter Type Sample Description
URL path parameters
nodeId Integer 1 Uniquely identifies a HyperCache instance.

Status 200 application/json

Object type: HyperCacheInstance

Download schema: hypercache-instance.read-detailed.schema.json

Response body:

{
    "nodeId": 3,
    "hostname": "dut3.primary.qa.lab.westford.akamai.com",
    "license": "cookie=4b99e07285882cf4b2d00b73fdb57e6c expires on 12/2020\nLicense         2300044041085119055\nMachineID       8788515039232315429\n4b99e07285882cf4b2d00b73fdb57e6c 2300044041085119055 8788515039232315429\nCoGB 1024MB",
    "serviceLabels": {
        "intraSite": [
            "172.31.3.1"
        ],
        "interSite": [
            "172.31.3.1"
        ],
        "clientServing": [
            {
                "ipAddress": "172.25.138.204"
            }
        ]
    }
}
  1. Determine the nodeId value of the HyperCacheInstance you want to get.

  2. Get the nodeId value by locating the particular node in the Aura Infrastructure API or by making a GET request to /api/lcdn-deployment/v1/hypercache/instances to locate the HyperCache instance.

  3. The operation responds with a HyperCacheInstance object.

Data

This section describes the data objects that the Aura LCDN Deployment API exposes.

Download the JSON schemas for this API.

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

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

HyperCacheInstance

HPC instance detailed read schema.

Download schema: hypercache-instance.read-detailed.schema.json

Sample PUT request:

{
    "nodeId": 3,
    "license": "cookie=4b99e07285882cf4b2d00b73fdb57e6c expires on 12/2020\nLicense         2300044041085119055\nMachineID       8788515039232315429\n4b99e07285882cf4b2d00b73fdb57e6c 2300044041085119055 8788515039232315429\nCoGB 1024MB",
    "serviceLabels": {
        "intraSite": [
            "172.31.3.1"
        ],
        "interSite": [
            "172.31.3.1"
        ],
        "clientServing": [
            {
                "ipAddress": "172.25.138.204"
            }
        ]
    }
}

Sample GET request:

{
    "nodeId": 3,
    "hostname": "dut3.primary.qa.lab.westford.akamai.com",
    "license": "cookie=4b99e07285882cf4b2d00b73fdb57e6c expires on 12/2020\nLicense         2300044041085119055\nMachineID       8788515039232315429\n4b99e07285882cf4b2d00b73fdb57e6c 2300044041085119055 8788515039232315429\nCoGB 1024MB",
    "serviceLabels": {
        "intraSite": [
            "172.31.3.1"
        ],
        "interSite": [
            "172.31.3.1"
        ],
        "clientServing": [
            {
                "ipAddress": "172.25.138.204"
            }
        ]
    }
}

HyperCacheInstance members

Member Type Required Description
HyperCacheInstance: HPC instance detailed read schema.
cachingMemoryOverrideMB Integer A value that you assign to the HyperCache node to override the amount of caching memory the HyperCache node uses. Specify the value in megabytes. Recommended caching memory is 1891 megabytes out of 3783 megabytes of total memory. Improperly configuring the HyperCache caching memory can negatively affect the CDN. You should not have to override the automatically calculated memory. However, if you choose to override the caching memory, we strongly recommend that you first contact Akamai Technical Support.
externalBandwidthLimitMbps Integer A value that determines the maximum external interface bandwidth on a node, in megabits per second. Request Router compares the bandwidth usage for each node with the maximum configured limit to help determine node availability.
hostname String Read-only. The unique fully qualified domain name for a HyperCache node.
license String The license for a particular HyperCache instance. The minimum length is 1 and the maximum length is 32767.
nodeId Integer Read-only. The unique identifier for a HyperCache node.
serviceLabels HyperCacheInstance.serviceLabels Service label definitions for a HyperCache instance.
HyperCacheInstance.serviceLabels: Service label definitions for a HyperCache instance.
clientServing HyperCacheInstance.serviceLabels.clientServing[] An IP address that you specify for serving client-facing traffic. You can optionally associate this IP address with an IpAddressTag.
interSite Array An IP address that you specify on the HyperCache node for inter-site traffic.
intraSite Array The IP address that you specify on an HyperCache node for intra-site traffic.
HyperCacheInstance.serviceLabels.clientServing[]: An IP address that you specify for serving client-facing traffic. You can optionally associate this IP address with an IpAddressTag.
ipAddress String The node’s IP address to which the HyperCache instance is bound. Specify this IP address for serving client-facing traffic.
ipAddressTagId Integer The unique identifier for an IP address tag. Use the IP address tag to route traffic on a per-IP address basis and to provide service differentiation based on HyperCache IP addresses.

RequestRouterInstance

Request Router instance detailed read schema.

Download schema: requestrouter-instance.read-detailed.schema.json

Sample PUT request:

{
    "nodeId": 1,
    "serviceLabels": {
        "clientServing": [
            "172.25.138.202"
        ]
    }
}

Sample GET request:

{
    "nodeId": 1,
    "hostname": "dut1.qa.lab.westford.akamai.com",
    "serviceLabels": {
        "clientServing": [
            "172.25.138.202"
        ]
    }
}

RequestRouterInstance members

Member Type Required Description
RequestRouterInstance: Request Router instance detailed read schema.
hostname String Read-only. The unique fully qualified domain name for a node.
nodeId Integer Read-only. The unique identifier for a Request Router node.
serviceLabels RequestRouterInstance.serviceLabels Service label definitions for a Request Router instance.
RequestRouterInstance.serviceLabels: Service label definitions for a Request Router instance.
clientServing Array List of IP addresses you can specify for a node. The maximum length is 1 and the minimum length is 2048.

Errors

This section provides details about the data object that reflects 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

In error cases, the API returns an HTTP Problem JSON object with the application/problem+json media type. For example, when you try to GET an instance that does not exist, the API responds with a JSON object similar to this example:

{
  "type" : "https://akzz-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/api/lcdn-deployment/errors#core.entity-not-found",
  "title" : "The requested entity could not be found",
  "detail" : "HyperCacheInstance 99999 does not exist",
  "instance" : "https://akzz-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/api/lcdn-deployment/v1/hypercache/instances/99999#fae1fd860940d25d",
  "entityType" : "HyperCacheInstance",
  "entityId" : 99999
}

HTTP status codes

This section lists the full range of response codes the API generates.

Code Description
200 The operation was successful.
201 Resource created.
400 Bad request.
401 Authentication failure.
403 The client doesn’t have the appropriate authority to perform the requested operation.
404 Resource not found.
405 Method not supported.
409 Conflict with the current state of the resource.
415 Unsupported media type.
503 Service is temporarily unavailable.