Cache Purge Guide

Overview

This document describes the API used to purge the cache.

Note A example cache purge script written in Python is available here: cache_purge_template.py (5 KB)

Cache purge request

A purge request is made by sending a JSON object to the cache purge API. There is a purge_request block that has an action field that specifies the type of purge request, and a uris block that contains uri objects, each of which has a match_mode and uri_pattern field.

 

Field/block Description
action The type of purge desired. There are two possible types of purges:
  • PURGE: the specified URIs will be purged from cache
  • EXPIRE: the specified URIs will be marked as expired, but will remain in the cache. This is a “soft" purge of content, allowing it to be served stale when:
    • the origin is down (unreachable)
    • the origin is responding with 5xx error codes

For more information on soft purges, see the Help Center article "Soft" Purge from Cache.

uris List of URIs to execute the purge on. Each URI object in the list needs a match_mode and a uri_pattern, which together identify the specific objects to purge.

There is no limit on the number of URI objects in a uris block.

match_mode Defines how the URIs are looked up in the cache. The possible values are:
  • EXACT_LITERAL
  • PREFIX_LITERAL

For details about these modes, see the section "Types of cache purge requests" below.

uri_pattern Specifies the URIs to be looked up. If match_mode is EXACT_LITERAL, this will be the pathname of a specific single object; if PREFIX_LITERAL this will be wildcard with a directory name, or filenames that begin with the same group of characters.

For details about these patterns, see the section "Types of cache purge requests" below.

Say you wanted to purge all cached images in the path /img and all CSS files in the path /css on the site acme.com. The purge request data would be:

"purge_request":{
   "action":"PURGE",
   "uris":[
      {
         "match_mode":"PREFIX_LITERAL",
         "uri_pattern":"http://acme.com/img/"
      },
      {
         "match_mode":"PREFIX_LITERAL",
         "uri_pattern":"http://acme.com/css/"
      }
   ]
}

Using cURL:

Execute the command

$ curl -k -u 'hsimpson@acme.com:doh!123' 'https://api.instartlogic.com/acme/v1/cache/purge' -d '{"purge_request":{"action":"PURGE","uris":[{"match_mode":"PREFIX_LITERAL","uri_pattern":"http://acme.com/img/"},{"match_mode":"PREFIX_LITERAL","uri_pattern":"https://acme.com/css/"}]}}' -X POST

where you would, of course, use your own authorization string and company name in place of the placeholders.

Using Advanced REST client plugin for Chrome:

  1. In the URL field at the top enter

    https://api.hq.instart.co/acme/v1/cache/purge

  2. Click the POST radio button.
  3. In the Headers field, add a header named Authorization with a value

    Basic <authorization string>

    where your authorization string consists of your username and password separated by a colon (:) and then base 64-encoded.

  4. Click Send.

The API server will respond with a JSON object similar to the following:

{
   "code": 201,
   "description": "OK"
   "purge_response": {
      "transaction_status_uri": "/transactions/67804160"
   }
   "transaction_id": 67804160
}

The value of code is the HTTP status code returned when the purge request is validated. Possible values are:

Code Description
201 Purge request was successfully submitted
403 Authentication issue – an invalid authtoken was used, or a bad password/username combination was used
400 Bad Request – caused if the cache purge API wasn't able to validate the purge request – for example, if the user isn't allowed to purge the domain, or a config for a specified path doesn't exist
5xx Server-side error. Any 5xx error means that there was an issue on the cache purge API infrastructure. If you see a 5xx, please contact Support.

Types of purge requests

The Instart Logic API allows for two types of cache purge requests: exact and prefix. Exact allows you to specify a specific file such as http://example.com/images/file.jpg. In this case, only that specific file would be purged. You can also specify a prefix purge such as http://example.com/images/, in which case anything in the images/ directory and any subdirectories would be purged.

You can change which mode you use by setting the value of match_mode using EXACT_LITERAL or PREFIX_LITERAL, depending on which mode you want to use. You can also use wildcards for the domain, as long as the wildcard is defined in one of the domain patterns present in one of your property configurations.

Some guidelines on forming valid uri patterns:

Some examples:

With match_mode set to EXACT_LITERAL, the purge_request block would be:

"purge_request": {
   "action": "PURGE", 
   "uris": [ 
      { 
         "match_mode": "EXACT_LITERAL", 
         "uri_pattern": "http://assets.example.net/images/file.jpg" 
      } 
   ]
} 

or, with a wildcard for the domain:

"purge_request": { 
   "action": "PURGE", 
   "uris": [ 
      { 
         "match_mode": "EXACT_LITERAL", 
         "uri_pattern": "http://*.example.net/images/file.jpg" 
      } 
   ] 
} 

This would purge the file /images/file.jpg in any domain that matches the wildcard pattern. For example, if there were domains images1.example.net, images2.example.net, and images3.example.net, and the domain *.example.net is listed in your property configuration, the file /images/file.jpg on each of those domains would be purged from the cache. With match_mode set to PREFIX_LITERAL, the purge_request block would be:

"purge_request": { 
   "action": "PURGE", 
   "uris": [
      { 
         "match_mode": "PREFIX_LITERAL", 
         "uri_pattern": "http://assets.example.net/images/" 
      } 
   ] 
}

or, with a wildcard for the domain:

"purge_request": { 
   "action": "PURGE", 
   "uris": [ 
      { 
         "match_mode": "PREFIX_LITERAL", 
         "uri_pattern": "http://*.example.net/images/" 
      } 
   ] 
}

This would purge all files in the /images directory in any domain that matches the wildcard pattern. For example, if there were domains assets1.example.net, assets2.example.net, and assets3.example.net, and the domain *.example.net is listed in your configuration, all files in the /images directory on each of those domains would be purged from the cache.

Note There is a rate limit of 2 cache purge requests per second, per customer. We have found that provides a reasonable limit and works well in practice. If you write any code that iterates through a list of files and fires off single cache purge requests for each, you can introduce a delay to ensure that you don't hit up against this limit. Alternatively, you can check the transaction ID returned from the purge request to poll the API for the status of the purge operation. In our example Python cache purge script, after a request is sent, we do this and poll the API for the status of the purge once every 10 seconds until we receive a status of "SUCCESS." This script can be downloaded here: cache_purge_template.py (5 KB)

Purge by custom cache key (advanced)

The cache purge API now allows purges to be specified with a custom cache key as well as with object hostname and path. As an example, you might want to be able to purge the cache based on a custom cache key you called device_type. You specify the purge by adding the cache_key_modifier_regex field to the purge request:

"purge_request": { 
   "action": "PURGE", 
   "uris": [ 
      { 
         "match_mode": "PREFIX_LITERAL",
         "cache_key_modifier_regex": "device_type_tablet",
         "uri_pattern": "http://*.example.net/images/" 
      } 
   ] 
}

The cache_key_modifier parameter can be a string or can use a wildcard for matching. If in the above example you wanted to purge everything that had a custom cache key whose name begins with device_type_, you would specify

         "cache_key_modifier_regex": "device_type_*",

The wildcard can only be specified as a suffix.

The cache_key_modifier parameter only works if match_mode is PREFIX_LITERAL. If specified with EXACT_LITERAL, the API will return a 400: Bad Request error.

Transaction status request

The transaction_id can be used to check the status of the purge request. You can do this as follows:

Using cURL

Execute the command

$ curl -k -u '<username:password>' 'https://api.instartlogic.com/<company_name>/v1/transactions/<transaction_id>' -X GET

where you would, of course, use your own user name, password, company name, and transaction ID in place of the placeholders.

Using Advanced REST client plugin for Chrome:

While the transaction is pending, the API server sends a response like:

{ 
   "code" : 200,
   "description" : "OK",
   "transaction_id" : 69737053,
   "transaction_response" : { 
      "begin_ts" : 1371703625,
      "end_ts" : -221447149,
      "percent_received_responses" : 87,
      "transaction_status" : "PENDING",
      "transaction_status_description" : "Transaction is pending"
   } 
}

When the transaction has succeeded, the API server sends a response like:

{ 
   "code" : 200, 
   "description" : "OK", 
   "transaction_id" : 9737053, 
   "transaction_response" : { 
      "begin_ts" : 1371703625, 
      "end_ts" : 1371703653, 
      "percent_received_responses" : 0, 
      "transaction_status" : "SUCCESS",
      "transaction_status_description" : "Completed" 
   } 
}
Important If you want to use wildcards for the domain, the wildcard must be present in the host_patterns block of your configuration.

Additional resources

For more information on caching, see the article How the Instart Logic Service Handles Caching for details.