Akamai 101: The Basics of Purging


Before discussing why and how to purge cached content, it's helpful first to take a quick look at caching. (For a deeper look at caching, check out "What You Need to Know About Caching".)

You get the most out of your content delivery network (CDN) when your content is stored (or "cached") on the CDN's edge servers, close to where the content is requested. Furthermore, you can get fine-grained control of the length of time each object is cached (or not) using either or both of two methods: caching rules and Time to Live (TTL). Here's an overview of each method:

Caching Rules

Caching rules control whether a given object is cached or not. A common way to increase performance is to use caching rules to cache content that doesn’t change very often. For example, images and PDFs files are fairly static, so you could create a caching rule that would cache .jpg and .pdf file extensions automatically. Caching rules can be as simple as that, or more complex, such as serving a different landing page to logged-in users.

Time to Live

Time to Live (TTL) indicates how long content stays in the edge server's cache before checking if there is new content on the origin. Once the TTL expires, the edge server checks with the origin to see if new content is available. If newer content is available, it’s served from the origin the next time it’s requested and thereafter cached at the edge. For static files, like images and pdfs, you can set fairly long TTLs, which greatly benefits performance. For time-sensitive content like a weekly newsletter or flash sale, shorter TTLs are helpful.


The Benefits of Purging

By efficiently utilizing the edge, caching rules and TTLs help you maximize application offload and reduce operating costs. More importantly, they help you improve performance for your end users. But what if you need to rapidly change your cached content?

That's where purging comes in.

Purging allows you to shortcut the TTL setting by defining long TTLs that maximize offload, and then remove old content and display new content from the origin—in a rapid and predictable manner—whenever you require it. You can purge content via an API call, or via the command line with Akamai CLI, or via the Akamai Control Center.

Here are five ways to specify the content you want to purge:

  1. By URL: You indicate a list of URLs to purge.

  2. By content provider code (CP code): You indicate the CP code (an integer), and all the content associated with that code is purged.

  3. By cache tag: Cache tags enable you to name and group related content. For example, you could create a group called “product-thumbnails” and then have the ability to purge the entire group. (For more, check out Introducing the Ability to Purge by Cache Tag.)

  4. By cache key (ARL): A cache key is a string used by the edge server to index objects in the cache. The cache key can be almost anything that's part of the client request, including query strings, HTTP request headers, some types of POST bodies, or even a characteristic of the client like the end user's country or the type of device. This is supported by the Fast Purge API.

  5. By wildcard or extension: You can also purge content by directory paths and file extensions. This method is less popular because it tends to be slower than the methods above.

How Purging Works

Once you submit a purge request through one of the available methods noted above, your request is then sent to the purge system which broadcasts the request to the edge servers.

When the edge servers receive the purge request, they look for the objects to purge in the cache (from both memory and disk) and take the appropriate action depending on whether the purge type is "Delete" or "Invalidate".

  • Delete: If the purge type is Delete, then the objects are physically deleted. Use delete when there’s no content to replace it with.  For example, you would delete content that was intended for internal audiences, and was inadvertently published.

  • Invalidate: If the purge type is Invalidate, the edge server expires the TTL of the object to ensure the edge server pulls a new copy of the object from the origin on the next request. This is done using an If-Modified-Request to ensure the edge server only does a full GET when there is a newer object in the origin than the one in the cache of the edge server. The TTL is marked expired, which causes the edge servers to fetch new content from the origin the next time it’s requested. Use Invalidate when you’re replacing the content with a newer version.

When you purge content from the edge, traffic that would normally be served at the edge now goes to your origin server. You will get a spike in traffic on your origin, the severity of which depends on how much content you purged. For this reason, be especially careful when purging large groups of content. Once the edge server caches are populated with new content, the spike will subside.

Tools for Purging

The table below shows four different methods you can handle purging and manage the expiration of content in your edge server cache, and the specific tools associated with each method:

Method Tools Available Estimated Processing Time on Production
Fast Purge

(for purging by URLs, CP codes, cache keys and cache tags)

Under 5 seconds
Media Services (for purging media content) 5 seconds to 40 minutes, depending on the operation
Enhanced Content Control Utility 30-40 minutes

1. Purging in Control Center

The examples below show you how to use Akamai Fast Purge to purge a sample landing page (sandbox.akamaideveloper.com) using three different methods: Control Center, the Akamai CLI, and the Fast Purge API. In each example, both HTTP and HTTPS are purged, because the scheme (i.e., the part of the URL before the colon) is part of the cache key/ARL (Akamai Resource Locator).How to Use Akamai Fast Purge

Control Center is ideal for one-off content purges (rather than automated/repeating purges).

To access Fast Purge in Control Center, click the Control Center Menu and then Purge cache Publish. Then indicate what you want to purge and how:

  • The object(s) you want to purge (URLs, CP codes, cache tags, or cache keys/ARLs)
  • Network to purge (staging/production)
  • Type of purge (Delete/Invalidate)
  • How you want to purge (URLs, CP codes, cache tags, or ARLs)

Here's an example screenshot that shows what you'll see:


2. Purging Using the Akamai CLI

The Akamai CLI can be very useful for automating purges from a CMS system or a CI/CD system that allows running system shell commands, as it does not require a programming language environment.

The purge example below uses the Akamai CLI. You can see in the response body that the request was accepted and would take around five seconds to process across the whole network.

$ akamai purge --section ccu invalidate --production https://sandbox.akamaideveloper.com/ http://sandbox.akamaideveloper.com/
Purging...... [OK]
Purged 2 objects (ETA: 5 seconds)

3. Purging Using the Fast Purge API

The Fast Purge API is the recommended way to automate ad-hoc content refreshing through an implementation in your favorite programming language or third-party CLI. The example below uses the Fast Purge API through a third-party CLI called HTTPie to purge two URLs. You can see in the response body that the request was accepted and would take around five seconds to process across the whole network.

$ http --auth-type=edgegrid -a ccu: POST :/ccu/v3/invalidate/url/production objects:='["https://sandbox.akamaideveloper.com/","http://sandbox.akamaideveloper.com/"]'

  "detail": "Request accepted",
  "estimatedSeconds": 5,
  "httpStatus": 201,
  "purgeId": "2c81d1b0-a11a-11e8-9b41-099799edf479",
  "supportId": "17PY1534399442272502-270820544"

Additional Resources

Fast Purge documentation