The Content Control Utility API

The Content Control Utility (CCU) API provides a programmatic interface for you to purge edge content. In this version, you can purge by URL, by Content Provider (CP) code, or cache tag.

For users of the legacy Content Control Utility REST API, this API leverages the Fast Purge Utility via Luna authentication. The Luna Control Center provides a graphical interface to the Fast Purge Utility for content administrators.

This guide details the most recent version 3 of the CCU API, which uses Fast Purge versus queue-based processing. For queue-based processing, see the Content Control Utility API v2.

For more information about Fast Purge, see CCU API Concepts.

Who Should Use This API

The CCU API is a simple API that automates content purge requests. Support for Fast Purge in the current version allows developers and architects to purge edge content by URL, CP code, or cache tag within approximately five seconds.

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

Getting Started

To get started with this API:

  • Review the API Introduction section on available tools.

  • Review API Provisioning to create your API access credentials and authorizations. When creating, adding, and naming clients for API access, do so under CCU APIs, not Luna APIs. Note that you can select all CP codes when configuring your API credentials. This means all current and future CP codes on the current contract, not all CP codes on the account.

  • Get help from our developer community or Technical Support, and provide feedback. You can also contact your account representative for support. We want to hear from you!

CCU API Concepts

This section describes the conceptual objects you deal with when interacting with this API, and provides pointers to where you can learn more.

  • Fast Purge: The Fast Purge utility completes purge requests within approximately five seconds. Fast Purge supports requests to invalidate or delete URLs and CP codes on Akamai Staging and Production networks. It will eventually support all purge methods.

  • Invalidation: Content invalidation, or refresh request, is the default purge action in most cases. An invalidation purge action causes Akamai edge servers to send an If-Modified-Since (IMS) request to the origin on subsequent requests for invalidated content. If the timestamp of the object at the origin is more recent than the one in cache, the latter is replaced by the new object from the origin. Otherwise, it is re-validated for the duration of the TTL. If an object does not have a Last-Modified header, a regular GET request is sent to origin.

    NOTE: To avoid serving stale content, ensure the Last-Modified-Timestamp (LMT) value on the origin server is updated to a newer timestamp than the LMT value of the current object.

  • Deletion: The purge action that removes the object from cache so that it is no longer available to be served to clients.Deletion operations result in an expensive GET request to the origin server, and prevents Akamai from serving this content stale if the origin server is down.

  • Content Provider (CP) Code: A CP code identifies a set, typically a subset, of content on your origin server. CP codes also provide additional granularity in reports and to track billing. Each contract has at least one CP code associated with it. You cannot apply the same CP code to content under more than one contract. If you are using Property Manager, see the Property Manager API (PAPI) to retrieve a list of CP codes available for a selected contract and group. PAPI also allows you to generate new CP codes, assign them to properties, and apply them within property rules.

  • Cache Key: The cache key is an index entry for an object in cache. By default, Akamai uses the entire uniform resource identifier (URI) and query string to identify cached objects. You can specify a custom cache key to cache different versions of an object based on differences in query parameters and other differences such as variations in device characteristics..

  • Cache Tag: An opaque label applied to content from the origin by way of the Edge-Cache-Tag header. Once a set of objects have been cached with a tag, they can be purged together with a single version 3 API call. You can apply many tags to any object, allowing you to purge by any overlapping set of classifications you define, such as black-friday, flash-sale, electronics, laptops, tablets. If an object matches any one of the tags in a purge request, then its cache will be refreshed. Note that cache tags are case-sensitive.

Cache tag constraints:

  • If there are multiple Edge-Cache-Tag headers in the origin response, only the first is considered.

  • Tags in headers are derived from the ABNF token format. (see RFC 7230). Tag characters are limited to this set: [A-Za-z0-9!#$%&'+-.^_`~].

  • Tag names cannot exceed 128 bytes.

  • Use commas to delimit more than one value in the Edge-Cache-Tag header.

  • End users do not receive the Edge-Cache-Tag header.

Sample Code and Use Cases

For sample code related to this API, see the api-kickstart repository.

For sample use cases, see the examples folder in the api-kickstart repository. It is continually being updated with new examples for Akamai APIs.

Rate Limiting

This API supports the following rate limits, which are based on the type and number of objects being purged per account.

  • For URL purges, up to 10,000 objects per 60 second window for a sustained rate, or 5,000 objects per 1 second for a burst rate.

  • For CP code purges, up to 100 purge requests per hour.

  • For cache tag purges, up to 5,000 objects per 3600 seconds.

When the X-RateLimit-Limit is reached, the API may respond with a 429 (Rate Limit Exceeded) error. If you receive this error, look at the value of the X-RateLimit-Next and X-RateLimit-Reset response headers to determine when your request can be fulfilled.

Anything that is limited to periods of time uses this format, where Reset provides the epoch time at which the Remaining value resets to the overall Limit:

  • X-RateLimit-Limit: Overall total limit, for example, 10000 for URLs and 100 for CP codes.

  • X-RateLimit-Name: Specifies the violated rate limiting rule, either SustainedRateLimit, BurstRateLimit, UrlSystemLimiter, UrlPerAccountLimiter, CpcodeSystemLimiter, or CpcodePerAccountLimiter.

  • X-RateLimit-Remaining: Remaining value, for example, 0.

  • X-RateLimit-Reset: An ISO 8601 timestamp, for example, 2017-02-17T00:56:41Z that represents the point in the future when the remaining value jumps back up to the overall total X-RateLimit-Limit.

  • X-RateLimit-Next: After the X-RateLimit-Limit has been reached within a given time period, this is the time at which the next request can be fulfilled.

The following URL sample response resulting in a 429 error:

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Date: Tue, 17 Feb 2017 00:56:35 GMT
Server: Apache-Coyote/1.1
X-RateLimit-Limit: 10000
X-RateLimit-Name: BurstRateLimit
X-RateLimit-Remaining": 0
X-RateLimit-Reset: 2017-02-17T00:56:41Z
X-RateLimit-Next: 2017-02-17T00:56:41Z

{
    "describedBy": "https://restccu.nss1.tn.akamai.com/ccu/v2/errors/Rate-Limit-Exceeded",
    "detail": {
        "detail": "This user has reached the request limit of 10,000 requests per 60 seconds",
        "rateLimit": 10000,
        "rateLimitName": "BurstRateLimit",
        "rateLimitRemaining": 0,
        "rateLimitReset": "2017-02-17T00:56:41Z",
        "rateLimitNextRequest": "2017-02-17T00:56:41Z",
        "status": 429,
        "title": "Rate Limit exceeded"
    },
    "httpStatus": 429,
    "supportId": "17PY1487292992176694-227919040",
    "title": "Rate Limit Exceeded"
}

Last modified: 8/25/2017