You appear to be offline. Some site functionality may not work.

Introducing batch API for surrogate key purge

Aug 2, 2017 in Performance

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.

batch api for surrogate key purge

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.

Performance

You may also like:

Subscribe to our newsletter

Subscribe to our newsletter

Server-sent events with Fastly

Server-sent events allow web servers to push real-time event notifications to the browser on a long-lived HTTP response. It’s a beautiful part of the web platform that’s severely underused by websites, and whether it’s flight…

Getting the most out of Vary with Fastly

You can use the Vary response header in creative ways, including A/B testing and internationalization. At the same time, many people still use Vary badly or misunderstand what it does; in this post, we’ll provide…

Optimizing HTTP/2 server push with Fastly

Since we made HTTP/2 generally available in November 2016, h2 traffic has been steadily growing as more customers migrate to the new version of the protocol; since the beginning of 2017, h2 traffic has increased…

Author

Tatsuhiko Miyagawa | Principal Architect

Tatsuhiko Miyagawa is a Principal Architect at Fastly, where he leads the engineering team behind the Fastly control plane systems. In his spare time, he’s a host of popular technology podcast Rebuild.

miyagawa