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
anforigin
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.jpg e.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=true literally 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"
}
completed
: Job is finished and files matching the pattern are purged successfully.queued
: In the queue to be executed.running
: Currently executing the jobfailed
: The job failed to execute.
If you have any trouble with the purge API, please contact Support
Comments
0 comments
Please sign in to leave a comment.