Cache-Group-Invalidation
When an unsafe request changes server state, related cached entries often need purging. The Cache-Group-Invalidation response header identifies cache groups to invalidate after an unsafe request completes.
Usage
HTTP caches store responses using request URLs as keys. When content changes, servers invalidate cached copies by sending invalidation signals. The Cache-Group-Invalidation header extends this mechanism by allowing servers to invalidate multiple related cache entries with a single response.
The Cache-Groups specification defines a framework for grouping stored responses under shared string identifiers. When a cache stores a response with a Cache-Groups header listing group names, the cache associates the stored entry with those groups. Later, when the server sends Cache-Group-Invalidation in response to an unsafe request (like POST, PUT, or DELETE), the cache may invalidate all stored responses belonging to the listed groups. Group-based invalidation is optional for caches.
This header appears only in responses to unsafe methods. Caches ignore Cache-Group-Invalidation on responses to safe methods like GET or HEAD, since safe methods do not modify server state and therefore do not trigger invalidation.
A common use case involves content collections. When an origin receives a
POST request creating a new article, the server includes
Cache-Group-Invalidation: "article-list" in the response. Caches
purge all stored responses previously tagged with the "article-list" group,
ensuring subsequent requests for listing pages fetch fresh data reflecting
the newly created article.
Values
The Cache-Group-Invalidation header value is a structured list of strings. Each string identifies a cache group to invalidate. Multiple group names are separated by commas.
Cache-Group-Invalidation: "group1", "group2"
Caches supporting the mechanism invalidate any stored response associated with at least one of the listed groups. The invalidation applies within the same origin, not limited to a single URL or path prefix.
Group names are opaque strings defined by the origin server. No standard naming convention exists, but practical deployments often use descriptive identifiers like "homepage", "catalog", or "user-sessions".
Example
After a POST request creates a new product, the server signals invalidation of the product catalog listing. The cache purges stored responses tagged with the "catalog" group.
Cache-Group-Invalidation: "catalog"
A PUT request updating a blog post invalidates both the post itself and the category index listing. The response lists two groups, triggering invalidation of all cached entries associated with either group.
Cache-Group-Invalidation: "post-123", "category-tech"
A DELETE request removing a user account invalidates multiple related cache groups covering user profiles, session lists, and admin dashboards.
Cache-Group-Invalidation: "users", "sessions", "admin-stats"
Rules that shape the behavior
The header works only on responses to unsafe requests. A cache MUST ignore the field on a response to a GET or any other safe method, which prevents ordinary browsing from purging groups, and ties invalidation to the POST, PUT, PATCH, and DELETE operations changing state.
Invalidation does not cascade. Invalidating a response invalidates responses sharing its groups, and stops there: groups belonging to those newly invalidated responses are left alone. One hop, deliberately.
Honoring the field is optional throughout. The specification leaves the whole mechanism permissive and defers stronger requirements to targeted cache-control profiles, so the header is a signal to caches choosing to listen rather than a command. No known cache listens yet, and production group purging runs on the vendor mechanisms, Cache-Tag among them, while the registered fields wait for implementations.