Content Control Utility API v2

Purge edge content by request. When writing new applications, use the Fast Purge.

Learn more:


Overview

The Content Control Utility (CCU) is Akamai’s technology for purging Edge content by request. The Luna Control Center provides a graphical interface to CCU for content administrators. The CCU REST API provides a programmatic interface for developers.

Prerequisites

To use the CCU REST API effectively, you must be familiar with your Akamai content model and the ARLs, URLs, and CP codes used to identify your content. Beyond that, the CCU REST API is a simple API for automating content purge requests.

For more information on content control using TTL (Time to Live) methods, See Time to Live (TTL) in Cache: Methods and Considerations.

CCU APIs

The following lists the CCU APIs and a brief description:

CCU API Call Action
/ccu/v2/queues/{queuename} POST Post a purge request to the queue
/ccu/v2/queues/{queuename} GET Get the length of the queue
/ccu/v2/purges/{purgeid} GET Get the status of a previous request

CCU request queues

Each account has its own default queue of purge requests. Within a queue, requests are serviced in the order in which they were submitted. When a request is submitted, the time it takes to service depends mostly on the number of items before it in the queue for that account. The default queue has a maximum size of 10,000 objects.

Emergency queue

When submitting purge requests, customers have access to an emergency queue for their account. Objects submitted to the emergency queue are serviced before the default queue belonging to the same account. To preserve the emergency queue for emergencies, the queue limit is set to 10 objects.

For instance, imagine your default queue has 5,000 items to purge and you have a web page that needs to be purged in a hurry. Waiting for the entire default queue to drain will take too long. This would be a good use for the emergency queue.

Objects in the emergency queue do not get serviced any faster than the default queue and do not take precedence over requests from other customers.

NOTE: Due to the asynchronous nature of the requests, the maximum queue length enforcement is only approximate. It is best practice to avoid using the emergency queue except for emergencies and not to rely on the quota enforcement to keep the queue small.

Responses

Purge requests return a 201 status code on success. It is important to check this status and handle it appropriately. If the status is not 201 then the purge request was most likely not received and will not be processed.

Responses are formatted as JSON. In particular, error responses are in the application/api-problem+json media type.

The following are common fields included in the response body:

  • httpStatus: The HTTP status code.

  • detail: Provides detail about the HTTP status code.

  • pingAfterSeconds: The minimum amount of time to wait before calling the Purge Status API.

  • supportId: The reference provided to Technical Support when needed.

For example, the following is a successful response to a purge request:

{
    "estimatedSeconds": 420,
    "progressUri": "/ccu/v2/purges/57799d8b-10e4-11e4-9088-62ece60caaf0",
    "purgeId": "57799d8b-10e4-11e4-9088-62ece60caaf0",
    "supportId": "17PY1405953363409286-284546144",
    "httpStatus": 201,
    "detail": "Request accepted.",
    "pingAfterSeconds": 420
}

These fields are described in more detail in the examples below and in the Reference section.

An example error response is:

{
    "supportId": "17PY1234567890123456-123456789",
    "title": "queue is full",
    "httpStatus": 507,
    "detail": "User's queue is full",
    "describedBy": "https://api.ccu.akamai.com/ccu/v2/errors/queue-is-full"
}

The title and detail fields describes the error. The describedBy link describes the error code in more detail. For instance:

<html>
    <head><title>queue-is-full</title></head>
    <body>The specified queue is full; additional objects cannot be added to it at this time.
    <p>The detail element of the response may contain additional information.</p>
    </body>
</html>

The CCU API responds with standard HTTP response codes. Below are some of the most common response codes, though other standard codes may also be returned.

Code Meaning Suggestion
200 Successful GET request
201 Successful POST of a purge request
400 Bad request Often JSON in a purge request
403 Forbidden Check the authorizations for the client and the ARLs being purged
415 Bad media type Typically a missing header Content-Type: application/json
507 Over queue limit Wait at least a few minutes to try again

Examples

Below are some examples of common usage for the CCU API.

Example 1: submit purge request

A purge request is submitted by sending a POST request to the /ccu/v2/queues/default or /ccu/v2/queues/emergency resource. The Content-Type must be application/json.

To construct the request object:

  • Optionally specify a JSON pair for type, which is either arl or cpcode. type defaults to arl if omitted.

  • With objects as the key, provide a JSON array of valid ARLs, URLs, or both, when arl is the type.

For cpcode type, supply an array of CP codes.

A simple purge request of type arl looks like this:

{
    "objects" : [
        "http://www.example.com/graphics/picture.gif",
        "http://www.example.com/documents/brochure.pdf"
    ]
}

A simple purge request of type cpcode looks like this:

{
    "objects" : [6848, 44],
    "action": "remove",
    "type": "cpcode"
}

Note that for CPCode purges, you must specify "type":"cpcode". On success, the response will contain the httpStatus of 201, indicating the request was successfully created.

{
    "estimatedSeconds": 420,
    "progressUri": "/ccu/v2/purges/57799d8b-10e4-11e4-9088-62ece60caaf0",
    "purgeId": "57799d8b-10e4-11e4-9088-62ece60caaf0",
    "supportId": "17PY1405953363409286-284546144",
    "httpStatus": 201,
    "detail": "Request accepted.",
    "pingAfterSeconds": 420
}

The pingAfterSeconds field indicates how long to wait before calling Purge Status. Use the progressUri link to make Purge Status calls.

The estimatedSeconds field is the estimated time before the request is processed by the Edge.

Example 2: check purge status

After making a purge request, you can check its status with a GET request to the progressUri. Always use the progressUri field returned from the purge request as the link to status information. (Do not derive the link from other details.) Use pingAfterSeconds to time the Purge Status call.

A typical successful response looks like this:

{
    "originalEstimatedSeconds": 480,
    "progressUri": "/ccu/v2/purges/142eac1d-99ab-11e3-945a-7784545a7784",
    "originalQueueLength": 6,
    "purgeId": "142eac1d-99ab-11e3-945a-7784545a7784",
    "supportId": "17SY1392844709041263-238396512",
    "httpStatus": 200,
    "completionTime": null,
    "submittedBy": "test1",
    "purgeStatus": "In-Progress",
    "submissionTime": "2014-02-19T21:16:20Z",
    "pingAfterSeconds": 60
}

A 200 response message indicates a successful status request. The purgeStatus return provides the status, which is either Done, In-Progress, or Unknown.

originalEstimatedSeconds references the estimated seconds given at the time the purge request was received and originalQueueLength indicates the length of the queue at that time.

submissionTime indicates the time the request was accepted, while completionTime indicates the time the request was completed. A value of null indicates that the request is not yet complete.

In the example above, the request is not complete and the pingAfterSeconds field is updated to recommend a time for the next status check.

Example 3: checking queue length

The CCU API allows you to check the approximate number of outstanding purge requests in your purge request queue. Each ARL or CP code submitted through a purge request increases the count by one. Although the CCU throttles the execution of purge requests to optimize network performance, there is still a limit of 10,000 objects in your queue. There is value in keeping your queue length short, because the time to complete the next purge is dependent on how many requests are ahead of it.

The resource to get the queue length is /ccu/v2/queues/{queuename}. The queuename is either default or emergency, as described above.

A typical successful response looks like this:

{
    "httpStatus" : 200,
    "queueLength" : 17,
    "detail" : "The queue may take a minute to reflect new or removed requests.",
    "supportId" : "17QY1321286863376510-220300384
}

A 200 response message indicates a successful request. The queueLength field provides the approximate number of outstanding requests.

Resources

This section provides details on the API’s set of URL operations.

API summary

Operation Method Endpoint
Request Queues
Get Current Queue Size GET /ccu/v2/queues/{queueName}
Add a Request POST /ccu/v2/queues/{queueName}
Purge Status
Get Purge Status GET /ccu/v2/purges/{purgeId}

Get current queue size

Retrieves the length of the queue length.

GET /ccu/v2/queues/{queueName}

Example: /ccu/v2/queues/default

Parameter Type Sample Description
Required
queueName String default Name of the queue. Currently supported options are default and emergency.

Status 200 application/json

Response:

{
   "supportId": "17QY1405953107052757-292938848",
   "httpStatus": 200,
   "detail": "The queue may take a minute to reflect new or removed requests.",
   "queueLength": 4
}

Add a request

Requests that the given objects (URLs, ARLs, or CPCodes) are purged.

POST /ccu/v2/queues/{queueName}

Example: /ccu/v2/queues/default

Content-Type: application/json

Request:

{
    "objects": [
        "/f/4/6848/4h/www.foofoofoo.com/index.php",
        "/f/4/6848/4h/www.oofoofoof.com/index2.php",
        "http://www.example.com/graphics/picture.gif",
        "http://www.example.com/documents/brochure.pdf"
    ],
    "action": "remove",
    "type": "arl",
    "domain": "production"
}

Parameter Type Sample Description
Required
queueName String default Name of the queue. Currently supported options are default and emergency.

Status 201 application/json

Response:

{
    "estimatedSeconds": 420,
    "progressUri": "/ccu/v2/purges/57799d8b-10e4-11e4-9088-62ece60caaf0",
    "purgeId": "57799d8b-10e4-11e4-9088-62ece60caaf0",
    "supportId": "17PY1405953363409286-284546144",
    "httpStatus": 201,
    "detail": "Request accepted.",
    "pingAfterSeconds": 420
}

On success, returns a 201 status and a response including the progressUri that can be used to retrieve the status of the request (see below).

NOTE: always check for the 201 status to confirm the request was successfully received.

The following table lists the properties of the JSON request:

Member Type Description
Required
objects Array List of URLs, ARLs, or CPCodes
Optional
action String The action to take, either remove (default) or invalidate
domain String The domain, either production (default) or staging
type String The type of the objects, either arl (default) or cpcode

For the action field, remove deletes the content from Edge server caches. The next time an Edge server receives a request for the content, it will retrieve the current version from the origin server. If it cannot retrieve a current version, it will follow instructions in your server configuration. invalidate marks the cached content as invalid. The next time a server receives a request for the content, it sends an HTTP conditional GET (If-Modified-Since) request to the origin. If the content has changed, the origin server returns a full fresh copy. Otherwise, the origin normally responds that the content has not changed, and the Edge server can serve the already-cached content.

Get purge status

Get the status of a purge request.

GET /ccu/v2/purges/{purgeId}

Example: /ccu/v2/purges/57799d8b–10e4–11e4–9088–62ece60caaf0

Parameter Type Sample Description
Required
purgeId String 57799d8b-10e4-11e4-9088-62ece60caaf0 The purgeId returned from the POST to the queue.

Status 200 application/json

Response:

{
    "originalEstimatedSeconds": 420,
    "originalQueueLength": 0,
    "supportId": "17SY1405954814899441-292938848",
    "httpStatus": 200,
    "purgeId": "57799d8b-10e4-11e4-9088-62ece60caaf0",
    "completionTime": "2014-07-21T14:42:18Z",
    "submittedBy": "client_name",
    "purgeStatus": "In-Progress",
    "submissionTime": "2014-07-21T14:39:30Z"
}

The following table describes the fields of the response JSON:

Member Type Description
httpStatus Number The HTTP status code
purgeStatus String The status of the request. Either In-Progress or Done.
completionTime String The approximate time that the request was completed, or null if not yet complete
supportId String Reference for this status request provided to CCare if needed
purgeId String The unique ID for the purge request
submissionTime String The approximate time the request was submitted
submittedBy String Identifies the submitter of the purge request
originalEstimatedSeconds Number Time in seconds originally estimated
originalQueueLength Number The approximate queue length at the time of the submission

Last modified: 12/12/2016