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[2]: "You are serving more than one format, language or compression from one URL.",You need the correct media type for a payload.
  caveats[2]: "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[4]: 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[8]{section,field,type,example}:
    headers,header,string,Accept
    headers,direction,string,Request
    headers,description,string,Client specifies preferred media types with qua…
    headers,example,string,"Accept: application/json, text/html;q=0.9, */*;…"
    headers,notes,string,Server responds with Content-Type or 406 Not Ac…
    media_types,type,string,application/json
    media_types,use,string,"REST APIs, configuration"
    media_types,notes,string,Standard for API responses; use application/pro…
data:
  headers[7]{header,direction,description,example,notes}:
    Accept,Request,Client specifies preferred media types with quality values (q-factor),"Accept: application/json, text/html;q=0.9, */*;q=0.8",Server responds with Content-Type or 406 Not Acceptable if no match
    Accept-Language,Request,Client specifies preferred natural languages,"Accept-Language: en-US,en;q=0.9,es;q=0.8",Server may return localized content or 406; often ignored in APIs
    Accept-Encoding,Request,Client specifies supported content codings (compression algorithms),"Accept-Encoding: gzip, deflate, br",Server responds with Content-Encoding; brotli (br) offers best compression for text
    Accept-Charset,Request,Client specifies acceptable character sets,"Accept-Charset: utf-8, iso-8859-1;q=0.5",Rarely used today; UTF-8 is de facto standard everywhere
    Content-Type,Request/Response,Media type of the request/response body,"Content-Type: application/json; charset=utf-8",Required for POST/PUT requests with body; server must respect or return 415
    Content-Encoding,Response,Compression applied to the response body,"Content-Encoding: gzip",Must match what client Accept-Encoding advertised; browser auto-decompresses
    Vary,Response,Indicates which request headers affect cache key for content negotiation,"Vary: Accept, Accept-Language",Critical for CDNs to cache multiple variants; missing Vary causes wrong content served
  media_types[8]{type,use,notes}:
    application/json,"REST APIs, configuration",Standard for API responses; use application/problem+json for errors (RFC 7807)
    application/xml,"SOAP, legacy APIs, RSS/Atom feeds",Still common in enterprise; use application/atom+xml for feeds
    text/html,Web pages,Always include charset=utf-8
    text/plain,Plain text responses,Use for non-structured text; browser won't render as HTML
    application/octet-stream,"Binary data, file downloads",Default when type is unknown; browser triggers download
    multipart/form-data,File uploads in HTML forms,Requires boundary parameter; use for file uploads not JSON payloads
    application/x-www-form-urlencoded,HTML form submissions (default),"Key=value&key2=value2 format; use for simple form data, not file uploads"
    application/graphql+json,GraphQL API responses,Emerging standard; use instead of application/json for GraphQL endpoints