Purging and versioned URLs

When content changes, the CDN must stop serving the old version. You have three tools. A versioned URL gives new content a new address, so there's nothing to purge. A purge by URL deletes specific objects. A purge by tag deletes every object that carries a label, however many URLs it spans.

The big idea

The best purge is the one you never run. Think of a new book edition with a new ISBN. The old edition stays on the shelves, but nobody asks for it, so nothing has to be pulled.

Fingerprinted asset URLs work this way. The build tool names a file after a hash of its contents, such as app.3f9a1c.js. The HTML points to that name. A code change makes a new hash, which makes a new URL. Old copies age out on their own.

Walking through it

Versioned URLs suit static assets. Those files get a one-year TTL and never revalidate:

Cache-Control: public, max-age=31536000, immutable

Only the small HTML document that references them needs a short TTL.

Purge by URL works for a few pages. But a price change can touch the product page, three category pages, search results and the homepage. Purging each URL by hand is error-prone.

Purge by tag solves that. The origin labels each response with the things it depends on:

Surrogate-Key: product-4521 category-shoes

When product 4521 changes, purge the tag product-4521. Every response that included it disappears from every PoP, usually within a second or two on modern CDNs. This lets you cache dynamic HTML for hours and still update it at once. Many news and e-commerce sites reach high hit ratios this way.

A soft purge marks content stale rather than deleting it. Combined with stale-while-revalidate, users don't see a miss spike after the purge.

Avoid purge everything during traffic peaks. It sends 100% of requests to the origin at once. That is the stampede the CDN exists to prevent.

Common mistakes

• Purging everything at peak. Every request then hits the origin together.
• Caching HTML for hours with no tags. You then have no fast way to update it on a change.
• Fingerprinting assets but leaving a long TTL on the HTML. The HTML keeps pointing at old files, so the new hash never gets used.

Check yourself

1. Why is a fingerprinted asset easier to manage than a purged one? A change creates a new URL, so there's nothing to purge. Old URLs simply stop being requested.
2. Why is purge-everything risky? Every request then goes to the origin at once, the stampede the CDN normally absorbs.

Key takeaways

• Fingerprinted URLs need no purge at all. Use them for static assets with one-year TTLs.
• Tag purges let dynamic pages stay cached for hours and still update instantly.
• Soft purges with stale-while-revalidate avoid miss spikes.
• Never purge everything during peak traffic.

Further learning

Fastly's guide to working with surrogate keys covers tag purging with examples.

Next, read about CDN hit ratio and cost, which turns hit ratio into dollars.