CDN caching can reduce origin traffic and improve page delivery, but an overly broad policy may expose private responses or keep outdated content online. This guide explains which headers, TTLs, cache keys, purge methods, and monitoring checks to use for static assets, HTML, APIs, and authenticated pages.
Overview
A content delivery network usually makes caching decisions from the response headers returned by your origin, together with rules configured in the CDN dashboard. The exact terminology varies between providers, so treat provider documentation as the final authority for supported directives, purge limits, default behavior, and cache-key controls.
There are three separate decisions to make:
- Can the response be shared? A public product page may be shared at the edge, while a user account page should normally remain private.
- How long may it be reused? Browser and edge caches can have different lifetimes.
- How is freshness restored? Versioned URLs, revalidation, or an explicit purge can remove outdated content.
Start with the response itself. Inspect production headers with browser developer tools or a command such as curl -I https://example.com/path. Check both a cache miss and a cache hit where possible. A CDN response often includes provider-specific headers showing whether the object was served from the edge, but those names and meanings differ by platform.
For broader performance planning, compare these decisions with the recommendations in the CDN and Website Caching Guide. Caching is one part of a complete website performance and security policy, not a substitute for access controls at the origin.
What to track
Cache-Control directives and TTLs
Use Cache-Control to state how a response may be stored and reused. The following reference covers common directives:
| Directive | Practical meaning | Typical use |
|---|---|---|
public | Allows shared caches to store the response when other rules permit it. | Public pages and static assets that contain no user-specific data. |
private | Restricts storage to a private browser cache rather than a shared CDN cache. | Personalized responses or pages containing account information. |
no-store | Requests that caches do not store the response. | Responses containing sensitive or highly temporary information, when appropriate. |
max-age=seconds | Sets the browser freshness lifetime. | Controlling how long browsers may reuse a response without rechecking. |
s-maxage=seconds | Sets a freshness lifetime for shared caches and may override max-age there. | Giving the CDN a different TTL from the browser. |
no-cache | Allows storage but requires validation before reuse. | Content that may be cached but should be checked for changes. |
must-revalidate | Requires a cache to obey freshness rules rather than serving a stale response under normal operation. | Policies where stale delivery is unacceptable. |
immutable | Signals that a fresh response is not expected to change during its lifetime. | Assets whose filenames include a content hash or release version. |
Do not assume that a long browser TTL can be corrected instantly with a CDN purge. A purge generally affects the provider's stored objects; a browser may continue using its own fresh copy until its browser TTL ends. For frequently changed HTML, choose a shorter browser TTL or use revalidation. For fingerprinted CSS, JavaScript, fonts, and images, a long TTL is usually easier to manage because the URL changes when the content changes.
Cache keys, cookies, and query strings
Record which request attributes form the CDN cache key. The path is usually important, but query-string handling, hostnames, request methods, selected headers, and cookies may also matter. A cache key that ignores a parameter can serve the wrong variant; one that includes unnecessary tracking parameters can fragment the cache and reduce hit rates.
Cookies deserve special attention. A response that sets or depends on a session cookie should not be treated as an ordinary public object without a deliberate design. Check whether the CDN bypasses caching when cookies are present, whether it includes selected cookies in the key, and whether origin rules remove or vary cookies safely. Never use a high cache hit rate as evidence that private data is protected.
Compression and revalidation
Track Content-Encoding and Vary behavior for compressed responses. If the response changes according to a request header, the cache must distinguish those variants correctly. Also monitor ETag and Last-Modified. These validators let a browser or edge ask whether an object changed instead of downloading the full response again. Confirm that any intermediary preserves the intended validation behavior.
Purge results and hit behavior
Keep a simple record of purge requests: time, scope, paths or tags, reason, and verification result. Check the actual URL from more than one network location when a release is important. A purge may be asynchronous, scoped to one distribution, or limited by the provider. Document those boundaries rather than assuming that “purge all” has the same meaning everywhere.
Cadence and checkpoints
Use a monthly or quarterly review for stable sites, and review immediately after a deployment pipeline, CDN configuration, authentication flow, or origin architecture changes.
At each release
- Confirm that versioned static assets have new URLs when their contents change.
- Inspect headers for the homepage, an asset, an API response, and an authenticated page.
- Verify cache status before and after a request, where the CDN exposes that information.
- Test a purge for the smallest necessary scope and confirm the updated content is returned.
- Check that browser behavior matches the release plan; a CDN purge cannot necessarily clear local browser caches.
During a monthly or quarterly review
- Compare cache-hit and origin-request trends by hostname, path group, and response status.
- Look for unexpected cache bypasses caused by cookies, authorization headers, query strings, or response headers.
- Review purge frequency. Repeated emergency purges may indicate missing asset versioning or an unsuitable HTML TTL.
- Test private pages with multiple accounts to ensure one user's response cannot be reused for another.
- Recheck provider documentation for directive support, purge quotas, dashboard terminology, and stale-serving options.
Keep a small policy table in source control. For each route group, record whether it is public, its browser and edge TTLs, its cache key, its purge method, and its owner. This makes a cache policy reviewable in the same way as an infrastructure or deployment change.
How to interpret changes
Visitors report old CSS or JavaScript after a deployment: inspect the asset URL first. If the URL did not change, use a targeted purge and consider content-hashed filenames. If the URL changed but old behavior remains, check HTML caching, service workers, browser cache headers, and whether the new HTML references the expected assets.
Updated HTML appears only after repeated refreshes: compare the HTML's browser TTL, edge TTL, validators, and purge status. A long max-age may explain browser reuse even after the edge has been purged.
Cache hits fall after a configuration change: inspect cache-key expansion, query-string normalization, cookies, authorization headers, and Vary. More unique variants can reduce reuse without indicating a CDN failure.
Personalized content appears in a shared response: treat this as a security incident. Temporarily disable shared caching for the affected route if necessary, review the cache key and response headers, purge affected objects, and verify the fix with distinct test accounts. Access control must remain enforced by the application and origin.
Origin traffic rises unexpectedly: determine whether objects are expired, bypassed, purged, or returning errors. A high miss rate may be intentional for private or rapidly changing content; interpret it against the route's policy rather than optimizing for hit rate alone.
When to revisit
Revisit this guide and your documented policy at least quarterly, and sooner when a recurring variable changes. Useful triggers include a CDN provider migration, a new domain or hostname, a framework or build-pipeline change, introduction of personalized content, a new API, a security review, an incident involving stale or private content, or a change to origin and failover architecture.
Make the next review practical: select representative URLs, capture their headers, record cache status from the edge and browser, test the purge scope, and compare results with the route policy. If the site has separate business, application, and static-asset domains, test each one. For high-availability designs, also confirm that failover responses carry safe cache headers; the high-availability cloud hosting architecture guide provides related infrastructure planning context.
Finally, add cache checks to deployment validation rather than relying on an incident to reveal a policy problem. A short checklist—public versus private classification, TTLs, cache key, validators, purge method, and post-release verification—can prevent both unnecessary purges and unsafe shared caching.