api: YAML JSON TOON Database
version: 1.0.0
format: json
dataset:
  id: 54
  slug: http-content-negotiation
  title: HTTP Content Negotiation
  description: "HTTP content negotiation: Accept, Accept-Language, Accept-Encoding, Accept-Charset headers, content type selection, and server-driven vs agent-driven negotiation."
  summary: "How clients and servers agree on a representation: Accept, Accept-Language, Accept-Encoding and Content-Type headers, the Vary header that records dependence, and common media types from JSON and XML to multipart and form encodings."
  use_when:
    - You are serving more than one format, language or compression from one URL.
    - You need the correct media type for a payload.
  caveats:
    - "Content negotiation interacts with caching: responses that vary must include a Vary header or caches may serve the wrong variant."
    - Servers may ignore Accept; the response Content-Type states what was actually sent.
  related:
    - http-request-headers
    - http-response-headers
    - http-caching-guide
    - http-methods-reference
  category: HTTP Status Codes
  category_slug: http-status-codes
  tags: http,content-negotiation,accept,accept-language,accept-encoding,media-types
  view_count: 0
  created_at: 1778695229
  updated_at: 1778695229
  entry_count: 15
  fields:
    - section: headers
      field: header
      type: string
      example: Accept
    - section: headers
      field: direction
      type: string
      example: Request
    - section: headers
      field: description
      type: string
      example: Client specifies preferred media types with qua…
    - section: headers
      field: example
      type: string
      example: "Accept: application/json, text/html;q=0.9, */*;…"
    - section: headers
      field: notes
      type: string
      example: Server responds with Content-Type or 406 Not Ac…
    - section: media_types
      field: type
      type: string
      example: application/json
    - section: media_types
      field: use
      type: string
      example: REST APIs, configuration
    - section: media_types
      field: notes
      type: string
      example: Standard for API responses; use application/pro…
data:
  headers:
    - header: Accept
      direction: Request
      description: Client specifies preferred media types with quality values (q-factor)
      example: "Accept: application/json, text/html;q=0.9, */*;q=0.8"
      notes: Server responds with Content-Type or 406 Not Acceptable if no match
    - header: Accept-Language
      direction: Request
      description: Client specifies preferred natural languages
      example: "Accept-Language: en-US,en;q=0.9,es;q=0.8"
      notes: Server may return localized content or 406; often ignored in APIs
    - header: Accept-Encoding
      direction: Request
      description: Client specifies supported content codings (compression algorithms)
      example: "Accept-Encoding: gzip, deflate, br"
      notes: Server responds with Content-Encoding; brotli (br) offers best compression for text
    - header: Accept-Charset
      direction: Request
      description: Client specifies acceptable character sets
      example: "Accept-Charset: utf-8, iso-8859-1;q=0.5"
      notes: Rarely used today; UTF-8 is de facto standard everywhere
    - header: Content-Type
      direction: Request/Response
      description: Media type of the request/response body
      example: "Content-Type: application/json; charset=utf-8"
      notes: Required for POST/PUT requests with body; server must respect or return 415
    - header: Content-Encoding
      direction: Response
      description: Compression applied to the response body
      example: "Content-Encoding: gzip"
      notes: Must match what client Accept-Encoding advertised; browser auto-decompresses
    - header: Vary
      direction: Response
      description: Indicates which request headers affect cache key for content negotiation
      example: "Vary: Accept, Accept-Language"
      notes: Critical for CDNs to cache multiple variants; missing Vary causes wrong content served
  media_types:
    - type: application/json
      use: REST APIs, configuration
      notes: Standard for API responses; use application/problem+json for errors (RFC 7807)
    - type: application/xml
      use: SOAP, legacy APIs, RSS/Atom feeds
      notes: Still common in enterprise; use application/atom+xml for feeds
    - type: text/html
      use: Web pages
      notes: Always include charset=utf-8
    - type: text/plain
      use: Plain text responses
      notes: Use for non-structured text; browser won't render as HTML
    - type: application/octet-stream
      use: Binary data, file downloads
      notes: Default when type is unknown; browser triggers download
    - type: multipart/form-data
      use: File uploads in HTML forms
      notes: Requires boundary parameter; use for file uploads not JSON payloads
    - type: application/x-www-form-urlencoded
      use: HTML form submissions (default)
      notes: Key=value&key2=value2 format; use for simple form data, not file uploads
    - type: application/graphql+json
      use: GraphQL API responses
      notes: Emerging standard; use instead of application/json for GraphQL endpoints