Designing a Tag-Based Akamai Cache Invalidation System

🧊 Introduction

Caching gets tricky when URLs change constantly (e.g. when query params include timestamps)

We were building a system that used GraphQL to serve real-time data from headless CMS, where URLs changed every day because of a date parameter. That made traditional URL-based cache busting impossible.

So we dropped URL-based caching entirely and built a tag-based, event-driven invalidation system instead. Cache purges happen automatically when content is published — not when the URL changes.

😵‍💫 The Problem: Unstable URLs Broke Caching

The GraphQL query we used required a date parameter to fetch time-sensitive data:

1query getData($date: Calendar) {
2  itemList(
3    filter: {
4      startAt: { _expressions: [{ value: $date, _operator: AT_OR_BEFORE }] }
5      endAt: { _expressions: [{ value: $date, _operator: AT_OR_AFTER }] }
6    }
7  ) {
8    items {
9      ... // response fields
10    }
11  }
12}

Because the date changed daily, it produced a new URL every time:

1https://<your-graphql-endpoint>?...&date=2024-09-07T00:00:00Z

This broke caching: Akamai treated each URL as unique, even if the underlying content hadn’t changed.

💡 The Fix: Cache by Tag, Not URL

Instead of relying on URLs, we built a system that:

Caches GraphQL responses in Akamai with a custom tag
On publish, sends a cache purge request to Akamai using that tag

The image below shows the overall architecture:

diagram

Triggering Cache Purge from headless CMS

In most headless CMS platforms, it’s possible to set up custom actions that fire when specific events occur — such as publishing content. We configured a trigger to send a request to API Gateway whenever content is updated.

That request includes key metadata (like what content was affected) in the request header. The backend (lambda) extracts this info, builds a cache tag, and uses it to invalidate Akamai cache.