Licensed CDN Content Control API v1

Purge content deployed on an Aura Licensed CDN, and deploy and operate your own content delivery network.

Learn more:


Overview

The LCDN Content Control API allows you to purge content deployed on an Aura Licensed CDN. Akamai’s LCDN offering allows you to deploy and operate your own content delivery network.

This API allows the CDN Operator or Content Provider to purge content from the LCDN. Purging removes outdated or unwanted content. Content can be purged one asset at a time, as a list of assets, or all assets within a directory using a wildcard. After an asset is purged, the first subsequent client request for the purged content results in a cache miss, and LCDN fetches a fresh copy from the origin server.

Who should use this API

This RESTful API allows the CDN Operator or Content Provider to configure and manage the following purge-related functions on the LCDN:

  • Purge cached content(s) of an origin from the LCDN by specifying a list of URI patterns

Getting started

Before you use the LCDN Content Control API for the first time:

  • Contact your Akamai representative to enable it for your account.

  • A contentProviderId is given to the Content Provider.

  • The Content Provider must obtain an authorization token using one of the supported flows using the client_id/client_secret from the application created by the CDN Operator.

  • Review Get Started on tools that Akamai provides for all its APIs.

  • Before you begin any API operations, you must obtain and store the value of the Content Provider ID(s) (contentProviderId) that you need from the AMC GUI. Using this Content Provider ID, you can obtain the origin ID(s) (originId) from which you want to purge content.

To obtain Content Provider IDs and Origin IDs, follow these instructions:

  1. Log in to the AMC GUI using an account with LCDN Operator privileges. The default administrator account is co@domain-name, where domain-name specifies the domain assigned to the AMC. Use the password you configured when you installed and configured the AMC.

  2. When the CDN Health dashboard opens, click Configure. Under Content Delivery, select Content Providers.

  3. In the Content Provider Management page, mouse over the name of a Content Provider to view the Content Provider ID.

  4. Store the value of the Content Provider IDs.

  5. To obtain a list of Origins associated with a particular Content Provider, please refer to the Content Delivery API documentation.

Resources

This section provides details on the API’s various operations.

Note that you will need to obtain the Origin ID (originId) externally. Please refer to the Getting Started section for instructions.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Content Control  
Purge Content POST /api/content-control/v1/purge
Support Resources  
List Errors GET /api/content-control/errors

Purge content

Add a new item to purge content for a particular originId. The uriPatterns list contains URI patterns that can match a file, for example: “/dir1/subdir1/unauthorized.flv”. If you want to remove all content assets within a specific directory, include the wildcard asterisk (*) at the end of the entry, for example: “/dir1/subdir2/*” will purge all the assets within /dir1/subdir2/.

POST /api/content-control/v1/purge

Content-Type: application/json

Request Body:

{
    "originId": 1,
    "uriPatterns": [
        "/1000.miss",
        "/dir/subdir/*",
        "/objects/movie1.mp4"
    ]
}

Status 200

List errors

Retrieve the listing.

GET /api/content-control/errors

Status 200

<html>
<head><title>Content-control API Errors</title></head>
<body>
<h1>Content-control API Error Descriptions</h1>

<a name="core.internal-error-exception"><h3>core.internal-error-exception</h3></a>
An internal error has occurred during processing.  Internal errors are not expected during normal system operation.  Please contact the system administrator for more information

<a name="core.unauthorized"><h3>core.unauthorized</h3></a>
The request did not contain valid authorization.  Obtain a valid authorization token from the authorization server and retry the request.

<a name="core.bad-request"><h3>core.bad-request</h3></a>
A bad request was received by the system.  The intent of the request could not be understood.  Please inspect the requested operation and ensure it is properly formed

<a name="core.constraint-violation"><h3>core.constraint-violation</h3></a>
The request received by the system contained more or more constraint violations.  More detail about each violation should be included in the error response.  Please check the error description for each respective error to learn more about each constraint violation.

<a name="core.not-null-violation"><h3>core.not-null-violation</h3></a>
A required property was missing from the request.  For many required properties, the system is able to determine a reasonable default.  However, not all properties have defaults, and thus must be specified.  Please retry the request with the property specified.

<a name="core.null-violation"><h3>core.null-violation</h3></a>
A property required to not be specified for a request was present.  Please retry the request without the property.

<a name="core.size-violation"><h3>core.size-violation</h3></a>
A property was specified with a value that was outside the valid range for the property.  The error message will often include the allowable minimum and maximum values.  Please retry the request with a valid value.

<a name="core.max-violation"><h3>core.max-violation</h3></a>
A property was specified with a value larger than it's allowable maximum.  Please check the documentation for the range of allowable values for this property

<a name="core.min-violation"><h3>core.min-violation</h3></a>
A property was specified with a value smaller than it's allowable minimum.  Please check the documentation for the range of allowable values for this property

<a name="core.pattern-violation"><h3>core.pattern-violation</h3></a>
A property value did not match the required pattern.  Please check the documentation for this entity for rules about property naming.

<a name="core.entity-not-found"><h3>core.entity-not-found</h3></a>
The requested entity could not be found.

<a name="core.entity-general-conflict"><h3>core.entity-general-conflict</h3></a>
A non-specific conflict error occurred.

<a name="core.hostname-violation"><h3>core.hostname-violation</h3></a>
The provided hostname was not properly formed.

<a name="core.ipv4-address-violation"><h3>core.ipv4-address-violation</h3></a>
The provided IPv4 address was not a well-formed address.

<a name="core.ipv6-address-violation"><h3>core.ipv6-address-violation</h3></a>
The provided IPv6 address was not a well-formed address.

<a name="core.mac-address-violation"><h3>core.mac-address-violation</h3></a>
The provided MAC address was not a well-formed address

<a name="core.non-existent-reference"><h3>core.non-existent-reference</h3></a>
The request referred to an instance of another entity that could not be found.  Please check the configuration and locate the correct instance.

<a name="core.entity-referenced-conflict"><h3>core.entity-referenced-conflict</h3></a>
An operation was attempted on an entity that is referenced by other entities.  This would cause a problem, for example, if the request was attempting to delete such an entity.

<a name="core.entity-property-conflict"><h3>core.entity-property-conflict</h3></a>
An attempt was made to set a property of an entity, but doing so would result in an invalid configuration.  For example, an entity class might require unique values for some properties.  If an entity with the given value already exists, then the system cannot accept the request.

<a name="core.invalid-parameter-violation"><h3>core.invalid-parameter-violation</h3></a>
A field was passed in a request that did not meet formatting constraints.  Please check the field and retry the request.

<a name="core.access-denied"><h3>core.access-denied</h3></a>
The request attempted to access a resource on which the principal does not have authority.

<a name="core.illegal-operation"><h3>core.illegal-operation</h3></a>
The requested operation is illegal

<a name="core.json-parse-error"><h3>core.json-parse-error</h3></a>
The received payload could not be parsed

<a name="core.json-mapping-error"><h3>core.json-mapping-error</h3></a>
The received payload was structurally valid, but could not be processed or mapped onto internal data types.  Check the content of the message for field type mismatches.

<a name="core.path-param-entity-field-mismatch"><h3>core.path-param-entity-field-mismatch</h3></a>
A parameter of the URI represents a field that is also specified in the request entity body.  When specified in the body, the values of the URI parameter and entity field must match for the request to be consistent.

<a name="core.invalid-path-param"><h3>core.invalid-path-param</h3></a>
A path parameter specified in the request URI did not meet expectations.

<a name="core.assert-condition-violation"><h3>core.assert-condition-violation</h3></a>
The provided value doesn't meet a predetermined condition (true/false).

<a name="core.readonly-property-violation"><h3>core.readonly-property-violation</h3></a>
An attempt was made to modify a property that is read-only.  Entity updates that specify the property must have a value matching the current value.

<a name="core.invalid-search-field-error"><h3>core.invalid-search-field-error</h3></a>
A search filter was presented that contained an unknown or unsearchable field in the query expression.

<a name="core.invalid-search-value-error"><h3>core.invalid-search-value-error</h3></a>
A search filter was presented that contained an invalid value for a field

<a name="core.invalid-search-expression-error"><h3>core.invalid-search-expression-error</h3></a>
A search filter was presented that was not syntactically correct.

<a name="core.illegal-reference"><h3>core.illegal-reference</h3></a>
An attempt was made to refer to one entity from another, but this operation was not deemed legal

<a name="core.entity-already-referenced"><h3>core.entity-already-referenced</h3></a>
An attempt was made to refer to an entity that is already referred to, where only a single reference is allowed

<a name="core.entity-optimistic-concurrency-failure"><h3>core.entity-optimistic-concurrency-failure</h3></a>
An attempt was made to optimistically update an entity, but the update was not made successfully.

<a name="core.method-not-allowed-error"><h3>core.method-not-allowed-error</h3></a>
The requested resource does not support the presented HTTP method

<a name="core.resource-not-found-error"><h3>core.resource-not-found-error</h3></a>
A resource was requested that does not exist.  Please check documentation for supported resource paths.

<a name="core.unsupported-media-type-error"><h3>core.unsupported-media-type-error</h3></a>
The request did not successfully complete content-type negotiation, as an unsupported content-type was presented.

<a name="core.general-client-error"><h3>core.general-client-error</h3></a>
A non-specific client side error occurred

<a name="core.service-unavailable-error"><h3>core.service-unavailable-error</h3></a>
Service is temporarily unavailable

<a name="content-control.purge-uri-pattern-invalid-violation"><h3>content-control.purge-uri-pattern-invalid-violation</h3></a>
Invalid URI pattern(s)

<a name="content-control.purge-limit-exceeded"><h3>content-control.purge-limit-exceeded</h3></a>
The maximum concurrent purge request limit has been exceeded. Please try again later.

</body>
</html>

Data

This section describes the LCDN Content Control API’s data objects that the API exposes.

Download the JSON schemas for this API.

Purge

Purge content (list of URIs) for a given origin

Download schema: origin-purge.schema.json

Sample POST:

{
    "originId": 1,
    "uriPatterns": [
        "/1000.miss",
        "/dir/subdir/*",
        "/objects/movie1.mp4"
    ]
}

Purge members

Member Type Description
originId Integer ID of the Origin object
uriPatterns Array List of URI patterns

Errors

This section provides details on 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 case of errors, the API returns an HTTP Problem Details JSON object with the application/problem+json media type.

HTTP status codes

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

Code Description
200 Successful purge operation.
400 Bad Request.
401 Authentication failure.
403 Purge operation is forbidden for the target content provider or origin.
405 Method not supported.
409 Target origin does not exist.
415 Unsupported media type.
500 Internal server error.
503 Too many purge requests. Service is temporarily unavailable.

Last modified: 2/2/2018