Getting Started with the OPEN CCU API

Members of the Developer Relations team interact with a lot of customers when on the road presenting API bootcamps. (Bootcamps are free for customers who want them! Ask your account rep to set one up.) We listen carefully to the challenges, goals and use cases of the developers we encounter, and found that one of the most common workflows customers ask about is purge. We've definitely got an API for that! In fact, purge is such a hot topic that we've moved pretty quickly through several API solutions, and today there are three choices available to you on the Developer Portal.

Earlier this year, the PurgeECCU and REST CCU resources were superseded by the OPEN CCU API. There are still a few use cases that require the ECCU interface, but the CCU interface should work for just about everyone who's getting started with the purge API. In this post, I'll point you to the most recent CCU API, walk through how it works and touch briefly on what it can do for you.

We're still evolving our purge solutions, and the next version of CCU featuring fast invalidation, is already in beta. The updated API is expected to be released in limited availability later this year, and generally available later next year. The new fast invalidation functionality will drastically bring down the time for invalidate requests to propagate through the network to 5 seconds or less. If you're interested in signing up for the Fast Invalidate beta or learning more about the upcoming CCU API version, visit the community page. We'll be covering this next version of the API in an upcoming blogpost, and will cover migration from V2 to V3 in a third post.

Overview

As a quick overview, the OPEN CCU API V2:

Allows developers to use a specific set of credentials to purge files or sets of files (by CPCode)
500 objects (either files or CPCodes) can be added in a single request
The queue can hold 10,000 objects
There are two different queues - default and emergency
The CCU API currently takes about 4 minutes to purge in most cases
You can choose to 'invalidate' or 'remove'
- 'invalidate' - Instructs the system to skip the cache on the next call to the resource. This is the best option for the vast majority of use cases.
- 'remove' - Removes the file from the cache. This is only necessary when there is a policy mandate to remove files immediately, and takes longer to execute.
Production or staging can be selected

Provisioning Credentials

The OPEN CCU API uses a slightly different provisioning system than other OPEN APIs. If you haven't provisioned a set of credentials for an OPEN API before, you can read the instructions on Authorizing your client on the Developer Portal. This will help you understand the instructions below for creating CCU credentials.

Go to Configure->Manage APIs to find the CCU provisioning section.
Select CCU APIs.
Choose a name for your client
Select "Authorizations"
Name the credential set
Choose CCU Read/Write and Read Only
Determine whether you want to allow this set of credentials to purge an entire CPCode as one action
Select default or emergency (although this doesn't really affect the credentials)
Choose the CPCode or CPCodes you want the credentials to have access to, or "ALL" if you want to have access to all fields.

Really, what's important to consider is:

Whether you want to restrict the credentials to a specific CPCode or CPCodes
Whether you want to allow purging an entire CPCode as a single action

Configuring your Client

Once you have grabbed your credentials, you can add them to your credential file. If you haven't done so already, clone or copy the github repository or install the docker container as described on the Developer Portal page entitled Download the sample client. Once you've done this, you can configure your system to work with the sample code by following the page on Configuring your Client. This process creates or updates an .edgerc file in your home directory with the various credentials for your system. When running the gen_edgerc.py script, please do it as follows so that the ccu.py script will work correctly:

python gen_edgerc.py ccu

Making CCU Calls

Use Cases for CCU

The most common use case for the OPEN CCU API is to remove files from the Akamai cache after they are changed in the CMS used by the content teams. Some companies also keep their images or other groups of files in a particular CPCode and purge those whenever there's an influx of changes. Just remember, the more files you purge at a given time, the more stress you'll put on your origin as the files are accessed and updated in the cache.

Sample Code

We provide sample code for CCU in the same api-kickstart repository that you downloaded to configure your client above. The examples/python/ccu.py script will purge a single file.

CAUTION: The purge request in the script when you get it won't work for you because it is requesting to purge a file that you don't have access to!

You can easily update the script and change the file name to see how the code works. Be sure to read through the CCU Documentation. Additionally, you can take a look at the other CCU sample code to determine how calls are made for other use cases.

Command Line

A great option if you want to explore the API from the command line is HTTPie, a command line utility designed for making API calls and returning useful information. Our team has created an authentication plugin for HTTPie so that it will work with our authentication model. Read our guide to setting up HTTPie to get started with this tool. The examples I'll show here will use HTTPie so you can see how it works.

Getting the request count in the queue:

http --auth-type edgegrid -a ccu: :/ccu/v2/queues/default

HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Connection: keep-alive
Content-Length: 161
Content-Type: application/json
Date: Sat, 15 Aug 2015 03:46:35 GMT
Server: Apache
Vary: Authorization

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

Purging a file:

Note that you'll need to use a file name that exists in your property. The sample below uses a file in our property.

Another Note: the \ used in command lines below indicates that the command continues on the next line and is only there for readability. You don't need to include either the \ or the newline in your command.

http --auth-type edgegrid -a ccu: :/ccu/v2/queues/default \ 
objects:='["https://developer.akamai.com/stuff/Akamai_Time_Reference/AkamaiTimeReference.html"]'

HTTP/1.1 201 Created
Allow: GET, HEAD, POST
Connection: keep-alive
Content-Length: 268
Content-Location: /ccu/v2/purges/f4be5bcf-4300-11e5-9c2b-03dde7548d39
Content-Type: application/json
Date: Sat, 15 Aug 2015 03:51:49 GMT
Server: Apache
Vary: Authorization

{
    "detail": "Request accepted.", 
    "estimatedSeconds": 240, 
    "httpStatus": 201, 
    "pingAfterSeconds": 240, 
    "progressUri": "/ccu/v2/purges/f4be5bcf-4300-11e5-9c2b-03dde7548d39", 
    "purgeId": "f4be5bcf-4300-11e5-9c2b-03dde7548d39", 
    "supportId": "17PY1439610708980988-396371136"
}

Now, you can call the third and final type of resource to see what the status is for your request. The progressUri from the previous call is the endpoint you'll want to call for this request.

http --auth-type edgegrid -a ccu: :/ccu/v2/purges/f4be5bcf-4300-11e5-9c2b-03dde7548d39

HTTP/1.1 200 OK
Allow: GET, HEAD
Connection: keep-alive
Content-Length: 401
Content-Type: application/json
Date: Sat, 15 Aug 2015 03:58:08 GMT
Server: Apache
Vary: Authorization

{
    "completionTime": null, 
    "httpStatus": 200, 
    "originalEstimatedSeconds": 240, 
    "originalQueueLength": 0, 
    "pingAfterSeconds": 60, 
    "progressUri": "/ccu/v2/purges/c86e0682-4301-11e5-a037-9978852b35d0", 
    "purgeId": "c86e0682-4301-11e5-a037-9978852b35d0", 
    "purgeStatus": "In-Progress", 
    "submissionTime": "2015-08-15T03:57:44Z", 
    "submittedBy": "B-3-112OHLC/OPEN", 
    "supportId": "17SY1439611087944715-268436672"
}

Summary

Purging files is a great task to delegate to an automated script. The process of purging manually is cumbersome and time consuming, and prone to user error if it is simply a manual part of a multi step process. Adding the purge functionality wherever it occurs naturally within your process will create a system where it's much more reliable and consistent.

I hope this has been helpful for you - please ask in the community if you have questions or clarifications, or comment on this post to get more details. The Developer Relations team, as always, is committed to your success!

maglietti/OpenCCU.md