Introducing batch API for surrogate key purge

Surrogate keys give Fastly customers a unique way to efficiently purge content from cache — instead of purging your entire site or each URL on an individual basis, you can tag related assets (like all images and descriptions associated with a single product) with surrogate keys, and these grouped URLs can be purged in a single request.

We're excited to introduce batch API for surrogate key purge, which allows you to purge content even more efficiently by purging multiple surrogate keys at once.

Batch API for surrogate key purge is useful for any team that requires a multiple surrogate key tagging scheme. A news site, for example, could use it to more efficiently update content when a story breaks: typically, when a new page is added, all possible pages (including the new item) have to be purged. If this is a news article, it would be top page, category index page, author index page, and so on. Imagine you’re tagging the category index page using a surrogate key scheme such as category/tech and author index pages like author/joe. When there’s a new article written by Joe in the Tech category, you need to purge all the pages tagged for these surrogate keys.

Previously, you would have issued these purges by sending multiple surrogate key purge requests, one for category/tech and another for author/joe. Now, with batch API for surrogate key purge, you can purge all related pages in just one request, as seen in the following example:

curl -X POST https://api.fastly.com/service/SERVICE_ID/purge \
  -H "Fastly-Key: FASTLY-API-TOKEN" \
  -H "Surrogate-Key: author/joe category/tech"

Read on to learn how to make use of this new API.

Batch API: how it works

Similar to our surrogate key purge API, you can send a POST request to the new batch API endpoint. We provide two ways to specify the list of surrogate keys to purge: HTTP header or JSON.

1. HTTP Header

POST /service/<service-id>/purge
Host: api.fastly.com
Fastly-Key: <API token>
Surrogate-Key: key1 key2 key3  

You can specify multiple surrogate keys in the Surrogate-Key header of the request (similar to how you use the Surrogate-Key header in the response header from your origin).

2. JSON body

POST /service/<service-id>/purge
Host: api.fastly.com
Fastly-Key: <API token>
Content-Type: application/json

{"surrogate_keys": ["key1", "key2", "key3"]}

You can encode the list of surrogate keys to purge in an array field, called surrogate_keys, in the JSON body of the HTTP POST.

Available in the control panel

Batch API for surrogate keys is also available in the Fastly control panel. Simply choose "Purge key" from the Purge menu, add as many keys as you’d like to purge (space separated), and it will purge multiple surrogate keys in one batch request.

We’re pleased to see some of our customers and partners already making use of batch API, and we hope you'll find it a useful addition to the Fastly purge API family. To learn more about purging, check out our guide and API documentation.