Fast Purge API v3

Purge content from your edge servers by URL, content provider (CP) code, or cache tag.

Learn more:


Overview

The Fast Purge API (formerly known as the Content Control Utility, or CCU, v3) provides a programmatic interface for you to purge edge content. In this version, you can purge by one or more URLs, Content Provider (CP) codes, or cache tags.

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.

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

Who should use this API

The Fast Purge API is a simple API that enables purging content at the edge. It allows developers and architects to purge individual URLs or grouped content via CP code or Cache Tag within approximately five seconds.

The API also comes with a CLI version that you can set up as a task within automation tools such as CircleCI or Jenkins.

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!

Fast Purge 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. You should typically Invalidate, as it will cause the edge server to treat content as though its TTL has expired. You should use Delete for compliance- or copyright-related purge requests, as it completely removes all content from servers.

    • 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 Fast Purge 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). Prohibited tag characters are whitespace characters or any of the following: *"(),:;<=>?@\[]{}

  • 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 uses rate controls to limit the number of API requests a single client can make per second.

Purge Type API Calls Purge Type Specific
Purge by URL 50 requests/sec 10K URLs/min
Purge by CP Code 50 requests/sec 1K CP codes purged per hour
Purge by Cache Tag 50 requests/sec 5K unique tags purged per hour

To purge more objects while remaining within defined limits, you should combine multiple objects into a single API call. A single API call may contain many objects of the same type, as long as the request body is smaller than 50,000 bytes.

When a client exceeds its allotted limit, the API responds with a 429 error, with various rateLimit* JSON members in the response body and X-Ratelimit* headers providing details.

HTTP/1.1 429 Too Many Requests
Date: Thu, 01 Mar 2018 19:26:25 GMT
Content-Length: 171
X-Ratelimit-Remaining: 0
X-Ratelimit-Limit-Per-Second: 30
X-Ratelimit-Limit: 100
Content-Type: text/html

{
    "status": 429,
    "rateLimitRemaining": 0,
    "supportId": "17RY1519390080947214-211628496",
    "rateLimit": 100,
    "title": "Rate Limit exceeded",
    "rateLimitCurrentRequestSize": 1
}

In addition, the API uses firewall rules to guard against DoS level traffic flows. These rules take effect when a single client attempts to submit hundreds of requests per second. The API responds with a 400 error for WAF rate-controlled clients.

HTTP/1.1 400 Bad Request
Content-Length: 427
Date: Thu, 01 Mar 2018 18:46:03 GMT
Connection: close
Content-Type: application/problem+json

{
    "type": "https://problems.purge.akamaiapis.net/-/pep-authn/request-error",
    "title": "Bad request",
    "status": 400,
    "detail": "WAF deny rule IPBLOCK-BURST4-27754",
    "instance": "https://akab-cj2eq2kcsv7cpt75-bi4ae4mdehbj2p4a.purge.akamaiapis.net/ccu/v3/invalidate/url",
    "method": "POST",
    "serverIp": "104.76.97.105",
    "clientIp": "24.2.26.125",
    "requestId": "1dd8d22",
    "requestTime": "2018-03-01T18:46:03Z"
}

Resources

The Fast Purge API (formerly called the Content Control Utility, or CCU, v3 API) allows you to purge edge content. You can use the API to purge by URL, by Content Provider (CP) code, or by cache tag.

Here is how fast invalidate and delete purges execute both with and without Fast Purge:

For all requests, you can choose either the staging or production network. If you do not specify a network, the operation applies to production.

NOTE: Cache tag operations (Invalidate and Delete) are only available to select beta customers.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Invalidations  
Invalidate by URL POST /ccu/v3/invalidate/url/{network}
Invalidate by CP Code POST /ccu/v3/invalidate/cpcode/{network}
Invalidate by Cache Tag POST /ccu/v3/invalidate/tag/{network}
Deletions  
Delete by URL POST /ccu/v3/delete/url/{network}
Delete by CP Code POST /ccu/v3/delete/cpcode/{network}
Delete by Cache Tag POST /ccu/v3/delete/tag/{network}

Invalidate by URL

Invalidates content on the selected URL for the selected network. You should consider invalidating content by default. This keeps each object in cache until the version on your origin server is newer. Deletion retrieves the object regardless, which can dramatically increase the load on your origin server, and would prevent Akamai from serving the old content if your origin is unreachable.

POST /ccu/v3/invalidate/url/{network}

Sample: /ccu/v3/invalidate/url/staging

Content-Type: application/json

Request Body:

{
    "objects": [
        "https://foo1.bar.com/some/path",
        "http://foo2.bar.com/some/other/path"
    ]
}
Parameter Type Sample Description
URL parameters
network Enumeration staging The network on which you want to invalidate or delete content, either staging or the default production network.

Status 201 application/json

Response Body:

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Invalidate by CP code

Invalidates content on the selected CP code for the selected network. You should consider invalidating content by default. This keeps each object in cache until the version on your origin server is newer. Deletion retrieves the object regardless, which can dramatically increase the load on your origin server, and would prevent Akamai from serving the old content if your origin is unreachable.

POST /ccu/v3/invalidate/cpcode/{network}

Sample: /ccu/v3/invalidate/cpcode/staging

Content-Type: application/json

Request Body:

{
    "objects": [
        12345,
        98765
    ]
}
Parameter Type Sample Description
URL parameters
network Enumeration staging The network on which you want to invalidate or delete content, either staging or the default production network.

Status 201 application/json

Response Body:

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Invalidate by cache tag

Invalidates content on the selected set of cache tags for the selected network. You should consider invalidating content by default. This keeps each object in cache until the version on your origin server is newer. Deletion retrieves the object regardless, which can dramatically increase the load on your origin server, and would prevent Akamai from serving the old content if your origin is unreachable. Invalidate by Cache Tag is available to select beta customers only.

POST /ccu/v3/invalidate/tag/{network}

Sample: /ccu/v3/invalidate/tag/staging

Content-Type: application/json

Request Body:

{
    "objects": [
        "black-friday",
        "electronics",
        "laptops",
        "tablets"
    ]
}
Parameter Type Sample Description
URL parameters
network Enumeration staging The network on which you want to invalidate or delete content, either staging or the default production network.

Status 201 application/json

Response Body:

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Delete by URL

Deletes content on the selected URL for the selected network. In most cases, you should invalidate rather than delete content.

POST /ccu/v3/delete/url/{network}

Sample: /ccu/v3/delete/url/staging

Content-Type: application/json

Request Body:

{
    "objects": [
        "https://foo1.bar.com/some/path",
        "http://foo2.bar.com/some/other/path"
    ]
}
Parameter Type Sample Description
URL parameters
network Enumeration staging The network on which you want to invalidate or delete content, either staging or the default production network.

Status 201 application/json

Response Body:

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Delete by CP code

Deletes content on the selected CP code for the selected network. In most cases, you should invalidate rather than delete content.

POST /ccu/v3/delete/cpcode/{network}

Sample: /ccu/v3/delete/cpcode/staging

Content-Type: application/json

Request Body:

{
    "objects": [
        12345,
        98765
    ]
}
Parameter Type Sample Description
URL parameters
network Enumeration staging The network on which you want to invalidate or delete content, either staging or the default production network.

Status 201 application/json

Response Body:

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Delete by cache tag

Deletes content on the selected set of cache tags for the selected network. In most cases, you should invalidate rather than delete content. Delete by Cache Tag is available to select beta customers only.

POST /ccu/v3/delete/tag/{network}

Sample: /ccu/v3/delete/tag/staging

Content-Type: application/json

Request Body:

{
    "objects": [
        "black-friday",
        "electronics",
        "laptops",
        "tablets"
    ]
}
Parameter Type Sample Description
URL parameters
network Enumeration staging The network on which you want to invalidate or delete content, either staging or the default production network.

Status 201 application/json

Response Body:

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Data

This section describes the data model for the Content Control Utility (CCU) API.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required to be present, regardless of whether its value is empty or null.
Member is optional, and may be omitted in some cases.

UrlRequest

Specifies a list of URLs to invalidate or delete.

Download schema: UrlRequest.json

Sample POST request:

{
    "objects": [
        "https://foo1.bar.com/some/path",
        "http://foo2.bar.com/some/other/path"
    ]
}

UrlRequest members

Member Type Required Description
objects Array Lists URLs to purge. Purges content for both http and https schemes.

UrlRequestWithHostname

Specifies a list of server paths to invalidate or delete for a common hostname.

Download schema: UrlRequestWithHostname.json

Sample POST request:

{
    "hostname": "origin.qux.com",
    "objects": [
        "/some/path/object1",
        "/some/other/path/object2"
    ]
}

UrlRequestWithHostname members

Member Type Required Description
hostname String Identifies the domain from which the content is purged.
objects Array Lists server paths. Purges content for both http and https schemes.

CpCodeRequest

Specifies a list of CP codes to invalidate or delete.

Download schema: CPCodeRequest.json

Sample POST request:

{
    "objects": [
        12345,
        98765
    ]
}

CpCodeRequest members

Member Type Required Description
objects Array For CP code-based operations, an array of the CP codes you want to purge.

TagRequest

Specifies a list of cache tags to invalidate or delete.

Download schema: TagRequest.json

Sample POST request:

{
    "objects": [
        "black-friday",
        "electronics",
        "laptops",
        "tablets"
    ]
}

TagRequest members

Member Type Required Description
objects Array An array of cache tag strings you want to purge.

Response

V3 Purge response schema

Download schema: Response.json

Sample POST response:

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Response members

Member Type Required Description
describedBy String The URL for the API’s machine readable documentation, for example, https://api.ccu.akamai.com/ccu/v2/errors/internal-error. It describes the error code in more detail.
detail String Detailed information about the HTTP status code returned with the response.
estimatedSeconds Integer The estimated number of seconds before the purge is to complete.
httpStatus Integer The HTTP code that indicates the status of the request to invalidate or purge content. Successful requests yield a 201 code.
purgeId String Unique identifier for the purge request.
supportId String Identifier to provide Akamai Technical Support if issues arise.
title String Describes the response type, for example, Rate Limit exceeded.

Errors

This section shows you how to handle various kinds of errors the Fast Purge API generates, lists the range of HTTP status codes along with their likely causes.

NOTE: It is strongly recommended that you code test the response. The response is not hard coded, and can be different.

The format of error response objects follows the JSON Problem Details standard, and are identified with the application/api-problem+json content type.

The following example shows an error response for a request processed by Fast Purge.

{
    "supportId": "17PY1234567890123456-123456789",
    "title": "Unauthorized",
    "httpStatus": 401,
    "detail": "You are not authorized to invalidate this resource.",
    "describedBy": "https://api.ccu.akamai.com/ccu/v3/errors/unauthorized"
}

The describedBy link describes the error code in more detail. For example, a link may provide the following information:

<html>
<head><title>unauthorized-url</title></head>
<body>Permission to purge an url was denied.<p>
The detail element of the response may contain additional information.</p>
</body>
</html>

HTTP status codes

The Fast Purge API responds with these standard HTTP response codes.

Code Description
201 Successful POST of a purge request.
400 Bad request. Often this is an error in the JSON purge request. Check all parameters.
401 The request requires authentication. Check credentials used to connect to the edge server.
403 Forbidden. The authorization token does not allow access to the resource. For example, the request may specify products not authorized on a contract. Check the authorizations for the client and the property configurations being purged.
413 Request entity too large. The request was denied because it exceeds the maximum message body size, which is 50,000 bytes. Review your request and edit as needed to be under the 50,000 byte limit.
415 Bad media type. Verify the following header is present in the request: Content-Type: application/json.
429 Too many requests. Exceeded the limit of requests per second (see Rate Limiting).
507 Insufficient Storage. The request was denied because it exceeds the purge limit. Retry your request after approximately 5 seconds.

Last modified: 6/14/2018