api: YAML JSON TOON Database
version: 1.0.0
format: yaml
dataset:
  id: 2808
  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
  entry_count: 12
  fields:
    - section: directives
      field: directive
      type: string
      example: max-age=<seconds>
    - 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; …
  category: HTTP Status Codes
  category_slug: http-status-codes
  tags: http,caching,cache-control,etag,cdn,performance,browser-cache
  view_count: 41
  created_at: 1778695229
  updated_at: 1778695229
data:
  directives:
    - directive: max-age=<seconds>
      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=<seconds>
      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: <date>; server responds 304 if not modified"
      notes: 1-second resolution; ETag is more precise and preferred for programmatic use