Skip to main content

Cache Purge API

Jon Sæterås
  • Updated

Images cached on the ImageEngine network can be removed (purged) from the cache purge interface either through the control panel or through an API. This API is a part of the more extensive ScientiaMobile API. The API documentation can be found here https://api.scientiamobile.com/docs/v1.

In order to make use of the API you need an API key. The API key can be obtained by reaching out to our customer success team. Please note, API keys will only be issued to subscribed users. 

Why you might not want to purge images

Before proceeding, a note on purging images from the cache:

Especially with time-sensitive items, Image versioning should be used wherever possible instead of relying on purging old versions of images.
For instance, these two URLs will link to the same filename but each is treated as its own instance. Using image versioning ensures that the newest version is pulled from the origin when the change occurs on your site.
Examples:

Note the new number following the “?v=” sign for the second URL
You do not necessarily need to version at the origin. You may update the image at the origin, and increment their version(s) in the site code that references the image.

 

Making a Cache Purge Request

The API documentation uses curl to make the requests to the API. The Postman app can also be used and might be more convenient if you need the API readily at hand.

Authenticate

The API requests are authenticated by the provided API key (token) in the Authorization HTTP request header. The value of the header is Bearer <your API key/token>.
NOTE:This HTTP header must be present in all requests to the API.

Find the Subscription ID to purge

https://api.scientiamobile.com/identity/v1/users/me/subscriptions will list all subscriptions on your account.

In the response, note the id of the subscription on which you want to purge the cache. Note that if you have other products from ScientiaMobile, these will also be listed. Filter the response where "type": "imgeng".

Find the origin

The purge request requires the origin location as input. The next step in preparation is to find the correct origin for the subscription.

https://api.scientiamobile.com/imageengine/cdn/v1/subscriptions/{subscription_id}/origins may return an array of origins:

[
  {
    "origin": "sample-origin.example.com",
    "is_origin_prefix": false,
    "in_use": true
  }
]

Make note of the origin you want to use in your purge request. Usually this is an origin where "in_use": true.

Note that the purge request makes use of the origin, and not domain name because multiple domain names can use the same origin.

Make a Purge Request

A POST request to https://api.scientiamobile.com/imageengine/cdn/v1/subscriptions/{subscription_id}/purge will execute the purge operation. The body of this request holds the origin from the previous step, and a pattern to match the file paths that will be purged from the cache.

{
"origin": "https://sample-origin.example.com",
"pattern": "/images/*.png"
}

The above example will purge all files in the /images/ folder on the origin https://img.example.com ending with .png.

If you intend to purge cache on the same subscription and origin many times in the future, you may save the subscription_id anf origin for later so that you don’t have to look it up every time.

The pattern

pattern is an expression ImageEngine will use to identify the images that will be purged. The expression is matched on the image path and file name.

A number of operators are supported:

Operator Description
* Match any number of characters in a single section of the path e.g. /foo/*.jpg will match /foo/test.jpg but not /foo/bar/test.jpg
** Match any character, any number of times, recursively e.g. /foo/**.jpg will match both /foo/test.jpg and /foo/bar/test.jpg
[...] Match any character out of a set of characters e.g. /foo/img[0-9][0-9].jpg matches /foo/img01.jpg and /foo/img32.jpg
? Match the proceeding character or range zero or one time e.g. /foo/imgA?.jpg matches both /foo/img.jpg and /foo/imgA.jpge.g. /foo/img[0-9]?.jpg matches both /foo/img.jpg and /foo/img1.jpg
{a,b,...} Match any of the patterns a or b or ... e.g. /foo/img.{jpg,png,jpeg}matches /foo/img.jpg, /foo/img.png, and /foo/img.jpeg
\ch Escape the special character "ch" e.g. /foo/img.jpg\?thumbnail=trueliterally matches /foo/img.jpg?thumbnail=true, as opposed to /foo/img.jpgthumbnail=true
Pattern examples
Pattern Description
**/* All files in all directories, recursively
**/*.jpg All files in all directories, recursively, ending in .jpg
/files/* All files in the "files" directory
/files/*.jpg All files in the "files" or "other" directory ending in .jpg
/{files,other}/*.jpg All files in all directories, recursively
/files/[a-zA-Z0-9].jpg Files in the "files" directory ending in .jpg where the filename is a single alphanumeric character, case-insensitive

Checking the Status of a Purge Request

When executed, the purge request will return a purge_id of the job. To check the status of a purge request, take note of the ID and make a request to https://api.scientiamobile.com/imageengine/cdn/v1/subscriptions/{subscription_id}/purges/{purge_id}.

The response will look something like this:

{
"purge_id": "11a38b9a-b3da-360f-9353-a5a725514269",
"origin": "https://img.example.com",
"pattern": "/images/*.png",
"created": "2019-07-02 15:32:17 +0000 UTC",
"status": "completed"
}
Possible statuses of a purge job are:
  1. completed: Job is finished and files matching the pattern are purged successfully.
  2. queued: In the queue to be executed.
  3. running: Currently executing the job
  4. failed: The job failed to execute.
 

If you have any trouble with the purge API, please contact Support 

Related articles

Comments

0 comments

Please sign in to leave a comment.