{ "api": "YAML JSON TOON Database", "version": "1.0.0", "format": "json", "dataset": { "id": 53, "slug": "http-caching-guide", "title": "HTTP Caching: Complete Guide", "description": "HTTP caching strategies: Cache-Control directives, ETag/Last-Modified validation, CDN caching, stale-while-revalidate, and browser cache behavior.", "summary": "A guide to HTTP caching directives and validation: Cache-Control values such as max-age, no-cache, no-store, private, public and immutable, and the validators ETag and Last-Modified, each with an example and notes on when it applies.", "use_when": [ "You are setting caching headers for static assets or API responses.", "You need to explain the difference between no-cache and no-store." ], "caveats": [ "no-cache does not mean 'do not cache'; it means revalidate before reuse. no-store is the directive that forbids storing.", "Shared caches such as CDNs and browser caches have different rules (s-maxage, private)." ], "related": [ "http-response-headers", "http-request-headers", "http-redirect-status-codes", "http-content-negotiation" ], "category": "HTTP Status Codes", "category_slug": "http-status-codes", "tags": "http,caching,cache-control,etag,cdn,performance,browser-cache", "view_count": 0, "created_at": 1778695229, "updated_at": 1778695229, "entry_count": 12, "fields": [ { "section": "directives", "field": "directive", "type": "string", "example": "max-age=" }, { "section": "directives", "field": "type", "type": "string", "example": "Freshness" }, { "section": "directives", "field": "description", "type": "string", "example": "How long the resource is considered fresh from …" }, { "section": "directives", "field": "example", "type": "string", "example": "Cache-Control: max-age=31536000 (1 year, for im…" }, { "section": "directives", "field": "notes", "type": "string", "example": "Relative to request time; use long values for v…" }, { "section": "validation", "field": "mechanism", "type": "string", "example": "ETag" }, { "section": "validation", "field": "header", "type": "string", "example": "ETag: \"abc123\"" }, { "section": "validation", "field": "description", "type": "string", "example": "Opaque identifier for a specific version of a r…" }, { "section": "validation", "field": "example", "type": "string", "example": "Client sends If-None-Match: \"abc123\"; server re…" }, { "section": "validation", "field": "notes", "type": "string", "example": "Strong ETags guarantee byte-for-byte identity; …" } ] }, "data": { "directives": [ { "directive": "max-age=", "type": "Freshness", "description": "How long the resource is considered fresh from the time of the request", "example": "Cache-Control: max-age=31536000 (1 year, for immutable assets)", "notes": "Relative to request time; use long values for versioned static assets" }, { "directive": "s-maxage=", "type": "Freshness (shared caches)", "description": "Like max-age but only for shared caches (CDNs), overrides max-age for shared caches", "example": "Cache-Control: s-maxage=3600, max-age=0", "notes": "CDNs respect s-maxage; browsers ignore it and use max-age" }, { "directive": "no-cache", "type": "Revalidation", "description": "Resource can be cached but must revalidate with origin server before use", "example": "Cache-Control: no-cache", "notes": "Does NOT mean 'don't cache' — it means 'check with server first'" }, { "directive": "no-store", "type": "No caching", "description": "Do not store in any cache (browser, CDN, proxy)", "example": "Cache-Control: no-store", "notes": "Use for sensitive data (banking, personal info) or highly dynamic content" }, { "directive": "private", "type": "Cache scope", "description": "Only cacheable by browser (private cache), not by CDNs/proxies", "example": "Cache-Control: private, max-age=3600", "notes": "Default for authenticated responses; use public for CDN-cached content" }, { "directive": "public", "type": "Cache scope", "description": "Cacheable by any cache including shared CDNs and proxies", "example": "Cache-Control: public, max-age=86400", "notes": "Required for CDN caching of content behind auth (with care)" }, { "directive": "must-revalidate", "type": "Revalidation", "description": "Once stale, the cached response cannot be used without successful revalidation", "example": "Cache-Control: max-age=3600, must-revalidate", "notes": "Prevents serving stale content even when offline" }, { "directive": "stale-while-revalidate", "type": "Stale handling", "description": "Serve stale content while fetching fresh version in background", "example": "Cache-Control: max-age=3600, stale-while-revalidate=86400", "notes": "Improves perceived performance; user gets instant response, fresh content loads async" }, { "directive": "stale-if-error", "type": "Error fallback", "description": "Serve stale content if origin server returns 5xx error", "example": "Cache-Control: stale-if-error=604800", "notes": "Graceful degradation during origin outages; use with monitoring" }, { "directive": "immutable", "type": "Freshness optimization", "description": "Resource will never change; browser skips revalidation checks even on user reload", "example": "Cache-Control: max-age=31536000, immutable", "notes": "Only for versioned assets (app.abc123.js); prevents unnecessary revalidation on reload" } ], "validation": [ { "mechanism": "ETag", "header": "ETag: \"abc123\"", "description": "Opaque identifier for a specific version of a resource, compared via If-None-Match", "example": "Client sends If-None-Match: \"abc123\"; server responds 304 Not Modified if unchanged", "notes": "Strong ETags guarantee byte-for-byte identity; weak ETags (W/) allow semantic equivalence" }, { "mechanism": "Last-Modified", "header": "Last-Modified: Wed, 21 Oct 2024 07:28:00 GMT", "description": "Timestamp of last modification, compared via If-Modified-Since", "example": "Client sends If-Modified-Since: ; server responds 304 if not modified", "notes": "1-second resolution; ETag is more precise and preferred for programmatic use" } ] } }