Kirsten Hunter

Moving to CCU V3, Now With Fast Purge!

Blog Post created by Kirsten Hunter Employee on Jul 21, 2016

OPEN V3 API - Featuring 5-second purge!

 

Earlier this year, we had a blog post featuring the CCU V2 {OPEN} API, which introduced several new features to the CCU Purge function.  We're excited to mention that many of our customers are already using a better, faster Purge API - which adds Fast Purge to the toolset and provides you the ability to get your content cleared almost instantaneously.  The first thing you will need to do is to request access to the Fast Purge beta. 

 

There are a few differences between the {OPEN} API V3 and earlier versions, as well as some items which have remained the same.

 

Moving from all older APIs:

  • Purges are processed instantaneously - there is no longer a notion of a queue, neither "default" nor "emergency".
  • There is not currently a way to check the status of a purge message you have sent.
  • You can add objects to a total of 50K per request.
  • You can choose to "invalidate" or "delete".
  • "production" and "staging" can be purged as separate commands.  This is detailed further down in this post.
  • If you want to jump directly to the documentation you can find it here.
  • The V3 code will work even before the fast purge is turned on for your properties, so you can implement the code and turn on the functionality as soon as it's ready.  These calls will be redirected to the V2 OPEN API on the back end.

Moving from the SOAP API or older CCU REST API:

  • No email notification is available.
  • A set of credentials per contract needs to be created (instead of credentials at the account level).
  • The ability to purge by CPCode is coming in the future.
  • You will need to learn how to provision credentials in LUNA.  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.
    1. Go to Configure->Manage APIs to find the CCU provisioning section.
    2. Select CCU APIs.
    3. Choose a name for your client
    4. Select “Authorizations”
    5. Name the credential set
    6. Choose CCU Read/Write
    7. Select default or emergency (although this doesn’t really affect the credentials)
    8. Choose the CPCode or CPCodes you want the credentials to have access to, or “ALL” if you want to have access to all files on all properties in your account.

Moving from CCU V2:

  • Some companies keep their images or other groups of files in a particular CPCode and purge those whenever there’s an influx of changes. In the near future, you will be able to group images or other files under a common content tag, and purge all of those assets in 5 seconds with a single request to purge the tag to the V3 API. Stay tuned.
  • Existing CCU V2 credentials will work going forward for CCU V3 calls as well

 

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

 

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_v3.py script will purge a single file.

 

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.

 

To get an idea of what's required to run this code, here's a sample using HTTPie.  Again, the full code is included in the api-kickstart repository, but I wanted to show you the call in the simplest format possible so you can see how straightforward it is.

 

In this sample, I will purge from the staging server, using invalidate.

Posting a request to the queue - httpie:

http --auth-type edgegrid -a ccu: :/ccu/v3/invalidate/url/production \
 hostname=bc.akamaiapibootcamp.com objects:='["/index.html"]'
HTTP/1.1 201 Created
Allow: POST
Connection: keep-alive
Content-Length: 170
Content-Type: application/json
Date: Wed, 29 Jun 2016 01:18:25 GMT
Server: Apache
Vary: Authorization

{
    "detail": "Request accepted", 
    "estimatedSeconds": 5, 
    "httpStatus": 201, 
    "purgeId": "5f45684a-3d97-11e6-aaa0-73dc7cf18dee", 
    "supportId": "17PY1467163102911830-244184256"
}

 

As you can see, using the new V3 OPEN API for invalidation is even easier than V2 was.  There are examples in the code of using v3 in PHP, Python, and node.  Examples for ruby and Perl will be coming soon.

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!

Outcomes