Images cached on the ImageEngine network can be removed (purged) from the cache purge interface either through the control panel or through an API.
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:
- https://foo.com/images/172609.jpg?v=1234
- https://foo.com/images/172609.jpg?v=1235
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.
Authenticating
The ImageEngine API is located at https://control-api.imageengine.io
In order make use of the API you'll need an API key. The API key can be found or created in the control panel provided that your plan has access to the API.
To authenticate your requests to the API, add the HTTP header x-api-key
with the value of your API key.
Sending a purge request
The endpoint for submitting a purge request is:
POST https://control-api.imageengine.io/api/v1/subscriptions/<subscription_id>/cache_purges
Make sure the request is a POST request and these headers are included:
x-api-key: <API_KEY>
accept: application/json
If you don't know your subscription ID, you can find it in the URL of your control panel when logged in.
The body of the post request may look like this:
{
"engine_id": <engine_id>,
"expression": "/images/*.png"
}
Locate the engine_id in the control panel from the URL in your browser when you're logged in and looking at the engine details.
The expression is a matching pattern which will identify the files to be purged. See below for more information.
Once the purge request is POST'ed, you can check the status of the purge:
Checking status of a purge request
The same endpoint can be used to check the status of a purge request, but now with a GET method:
GET https://control-api.imageengine.io/api/v1/subscriptions/<subscription_id>/cache_purges
Remember to include the API key in the request:
x-api-key: <API_KEY>
The expression syntax
The expression syntax makes ImageEngine 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
|
\ |
The backslash \ is used to escape the character immediately after it. For example /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 |
If you have any trouble with the purge API, please contact Support
Comments
0 comments
Please sign in to leave a comment.