Set headers with intent.
A cache policy describes which responses may be stored, when they may be reused, and when validation is required. Choose those rules for each response class. This reference connects the main directives to public assets, changing pages, and sensitive content so configuration follows the application.
Classify the response first
Start with the response's audience and lifetime. A stylesheet with a content hash in its filename can have a different policy from the HTML that references it. A personal account page needs a different policy again. Document which request inputs change the result before configuring a cache key.
| Response | Policy direction | Required check |
|---|---|---|
| Public versioned asset | Explicit freshness; immutable when guaranteed | New bytes receive a new URL |
| Changing public HTML | Short freshness or validation | Updates appear within the intended interval |
| Sensitive personal data | No shared storage; no-store when needed | Separate sessions never share private responses |
These are design directions, not settings to paste across an entire domain. Use the actual publishing process and privacy requirements to choose the policy. Confirm how your CDN's explicit rules interact with the headers emitted by the origin.
Know what each directive means
max-age defines a freshness lifetime in seconds. s-maxage applies to shared caches and takes precedence there over max-age. The private directive excludes shared storage while allowing a private cache, such as a browser cache, to store the response.
no-cache permits storage but requires validation before reuse. no-store instructs caches not to store the response. They solve different problems. An ETag can support conditional validation, while Vary identifies request-header differences that affect response selection. Do not assume a cookie alone establishes a safe privacy policy.
Verify variation and publishing together
List parameters, headers, and session conditions that alter the output. Keep meaningful variations distinct without creating unnecessary entries for irrelevant inputs. Test language, image-size, and authentication differences where they apply. A high reuse rate is only useful when the returned representation is correct.
For public versioned assets, publish the new files before HTML begins referencing them and retain previous versions while they remain needed. Validate fresh, repeated, conditional, and private requests through the delivered endpoint. Our full caching guide covers the protocol details, and the testing checklist turns the policy into observable checks.