Introduction

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, refer to the following overview:

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 requests through OPEN, customers also 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 Customer Care 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.


Last modified: 12/6/2016