Short answer: An image cache key should change when the source bytes or output pixels change, and remain stable when irrelevant request details change. Base it on a versioned source, canonical transformation, and representation variant, then test the actual key behavior at every cache layer.
Image systems commonly have two related identities. The transformation service stores a derivative under an internal key, while the CDN stores an HTTP response under an edge key. If those rules disagree, the system can generate duplicates, serve the wrong format, or keep stale bytes after a source update.
Which inputs must affect identity?
Start with source identity and source version. An asset ID alone is insufficient if its bytes can be replaced. A version number or content hash makes each revision unambiguous and enables long-lived immutable caching.
Every normalized operation that changes pixels must also affect identity: width, height, fit, crop, focal point, orientation, quality, format, background, and relevant effects. The URL anatomy guide shows how to canonicalize these fields.
If output varies by a request header, that variation needs a correct cache strategy. Automatic format often depends on Accept. Private responses may depend on authorization but still represent the same underlying bytes. Decide whether access proof changes storage identity, delivery eligibility, or both.
Which inputs should not affect identity?
Tracking parameters, arbitrary query order, request IDs, and expired signatures usually should not create different pixel objects. Strip or normalize them before derivative identity is calculated. At the CDN, configure which query parameters matter rather than blindly including everything.
Do not place secrets in a cache key or loggable URL. A signature is a proof, not a transformation. Some systems validate it and then normalize to a content key; others cache the signed URL as received. Understand the provider’s behavior before selecting expiry times and cache lifetimes.
Cloudflare documents configurable dimensions in its cache key guidance. HTTP cache behavior, including freshness and validation, is defined in RFC 9111. Your image derivative rules sit on top of those semantics.
How does canonicalization prevent fragmentation?
Equivalent requests need one serialization. w=800&q=70 and q=70&w=800 should not create two entries. Neither should w=0800, a redundant default crop, or two aliases for the same fit behavior.
Normalize in one typed URL builder. Sort fields, choose one spelling, round values, omit defaults, and reject unknown operations. If the provider normalizes internally but the CDN caches raw URLs, your application still needs canonical URLs to avoid edge duplicates.
Presets should resolve deterministically. If a named preset changes meaning, version the preset. Silent changes can make one visible URL refer to old pixels at one edge and new pixels at another.
What can go wrong with automatic format?
If the same URL returns AVIF to one browser and JPEG to another, the cache must distinguish those representations. Standard Vary: Accept can express the relationship, but some CDNs use product-specific normalization to reduce the enormous variety of raw Accept headers.
Verify with real requests. Send explicit capability headers, inspect Content-Type, Vary, age, and cache status, then repeat in both orders. A cache poisoning bug may only appear when the less-capable client follows the more-capable one.
Format can also be explicit in the URL. This produces simple keys and observability at the expense of more markup or application logic. The format decision guide compares the approaches.
How should invalidation work?
Prefer versioned URLs over broad purges. When an original changes, emit a new source version. The old immutable derivative can expire naturally, while new requests cannot be confused with it.
Purge remains useful for security incidents, legal removal, or a faulty transformation. Document whether a purge removes edge responses, derivative storage, or both. Test propagation time and partial failure rather than assuming one API call reaches every layer.
Use reasonable negative caching for missing assets, but avoid turning a transient upload race into a long-lived 404. The upload workflow should publish delivery references only when assets are ready.
How do you test a cache key policy?
Create a matrix of requests that should match and requests that must differ. Reorder parameters, add ignored tracking data, vary a meaningful width, change source version, test format negotiation, and try expired versus valid signatures. Record response hash, content type, age, cache status, and timing.
Sample production keys by normalized transformation. A sudden rise in unique variants per asset suggests a caller bypassed the width ladder or added an unbounded value. The guide to preventing variant explosion turns that signal into policy.
Good cache identity is predictable enough to explain during an incident. If the team cannot state why two requests share or do not share bytes, the key design needs to be made explicit before traffic makes the ambiguity expensive.
Leave a Reply