{
  "id": "content-negotiation",
  "title": "Content negotiation",
  "lang": "en",
  "source_lang": "en",
  "summary": "Content negotiation is an HTTP mechanism for selecting a representation of a resource according to client preferences, such as media type, language, or compression format.",
  "category": "computer-science",
  "subcategory": "networks-security",
  "type": "concept",
  "aliases": [
    "HTTP content negotiation"
  ],
  "generated_at": "2026-11-06",
  "model": "pro/gpt-6.1-sol",
  "url": "https://aiwiki.page/en/content-negotiation/",
  "translations": {
    "zh-Hans": {
      "url": "https://aiwiki.page/zh/content-negotiation/",
      "json": "https://aiwiki.page/zh/content-negotiation.json"
    }
  },
  "sections": [
    {
      "heading": "",
      "text": "Content negotiation is a mechanism in the Hypertext Transfer Protocol (HTTP) for choosing among different representations of the same resource. A client can express preferences for a representation’s media type, natural language, or content coding, and a server can use those preferences when constructing its response. For example, one resource might be available as an HTML document or JSON data, in several languages, and with or without compression. Content negotiation allows these alternatives to be associated with the same resource identifier rather than requiring a different address for every combination."
    },
    {
      "heading": "Resources and representations",
      "text": "HTTP distinguishes a resource from its representations. A resource is the target identified by a URI; a representation consists of data and metadata that convey the resource’s state in a particular format. Negotiation selects a representation, not necessarily a different resource.\n\nFor example, a weather resource could provide:\n\n- An HTML page for interactive viewing.\n- A JSON representation for software clients.\n- English and French versions of its explanatory text.\n- Compressed and uncompressed versions of each representation.\n\nThese dimensions are distinct. A media type, such as text/html or application/json, describes the data’s format and processing model. A language tag, such as en or fr, identifies the intended audience’s language. A content coding, such as gzip or br, describes a transformation applied to the representation, usually for compression.\n\nContent negotiation is especially important on the Web and in application programming interfaces that support multiple output formats. However, HTTP does not require every resource to offer alternatives or every server to honor every expressed preference."
    },
    {
      "heading": "Main negotiation models",
      "text": "Proactive negotiation\n\nIn proactive negotiation, also called server-driven negotiation, the server selects a representation using information supplied with the request. The client commonly sends preference fields such as Accept, Accept-Language, and Accept-Encoding.\n\nThis model can deliver a suitable representation in a single request–response exchange. Its limitations include incomplete knowledge of the user’s intentions, the disclosure of preference information, and increased complexity for shared caches.\n\nServers may also consider request characteristics such as the client software or device capabilities. Such selection is less explicit than an Accept preference and can be unreliable when inferred from broad identifiers such as a user-agent string.\n\nReactive negotiation\n\nIn reactive negotiation, also called agent-driven negotiation, the server supplies information about alternatives, and the client or user selects one. A response might present links to different language versions or formats.\n\nHTTP’s 300 Multiple Choices status can support this approach. A 406 Not Acceptable response can also describe available alternatives when the server is unwilling to supply a default representation. HTTP does not define a universal response-body format or automatic selection procedure for all such cases.\n\nReactive negotiation can make choices more transparent, but obtaining the selected representation may require another request. A language-selection page is a common user-facing example, although similar interfaces can also be implemented without negotiation-specific status codes.\n\nTransparent negotiation\n\nTransparent content negotiation is a historical approach intended to let intermediaries participate in selecting representations using explicit descriptions of available variants. It was specified experimentally in RFC 2295 in 1998, with associated feature-negotiation work.\n\nIt did not become the dominant deployment model. Most contemporary systems rely on proactive negotiation, explicit links to alternatives, or application-specific selection mechanisms."
    },
    {
      "heading": "Request preferences and response metadata",
      "text": "The principal fields serve different roles:\n\nRequest field | Expresses a preference for | Related response metadata\nAccept | Media types | Content-Type\nAccept-Language | Natural languages | Content-Language\nAccept-Encoding | Content codings | Content-Encoding\nAccept-Charset | Character encodings | The charset parameter of Content-Type, where applicable\n\nAccept-Charset is deprecated in modern HTTP specifications. Widespread use of UTF-8 has reduced the need to negotiate character encodings, while detailed charset preferences can expose identifying information.\n\nThese request and response fields are not interchangeable. In a request containing a body, Content-Type describes the representation being sent to the server; Accept describes preferences for the response. A request can therefore send JSON while asking to receive HTML.\n\nSimilarly, Content-Encoding: gzip describes compression applied to the representation. It is not a media type and is distinct from transfer coding or transport framing.\n\nQuality values\n\nPreference fields commonly support a quality value, written as a q parameter. Values range from 0 to 1, with up to three decimal places. An omitted value defaults to 1; a value of 0 means that the corresponding alternative is not acceptable under that preference.\n\nFor example:\n\nAccept: text/html, application/json;q=0.8, */*;q=0.1\nAccept-Language: fr, en;q=0.7\nAccept-Encoding: br, gzip;q=0.8\n\nThis request favors HTML over JSON, French over English, and Brotli compression over gzip.\n\nQuality values are relative preferences, not probabilities. Nor do they define one universal scoring formula across all negotiation dimensions. Server selection policy, available variants, and the matching rules of each field also matter.\n\nFor Accept, more specific media ranges take precedence when determining the quality assigned to a representation. Thus:\n\nAccept: text/*;q=0.8, text/html;q=0.2\n\nassigns HTML a quality of 0.2 rather than 0.8.\n\nContent-coding preferences have additional rules. The identity token denotes the absence of a content coding and is generally acceptable unless excluded. An empty Accept-Encoding field expresses a preference for no content coding; an absent field does not mean that compression is forbidden."
    },
    {
      "heading": "Example exchange",
      "text": "A client might request a French JSON representation compressed with gzip:\n\nGET /weather HTTP/1.1\nHost: example.test\nAccept: application/json\nAccept-Language: fr\nAccept-Encoding: gzip\n\nThe server could respond:\n\nHTTP/1.1 200 OK\nContent-Type: application/json\nContent-Language: fr\nContent-Encoding: gzip\nVary: Accept, Accept-Language, Accept-Encoding\n\nThe response body would contain gzip-compressed JSON bytes. The response fields describe what was actually selected; clients should not assume that their first preference was honored merely because they requested it.\n\nIf the server cannot satisfy a preference, it can return 406 Not Acceptable or, where permitted, disregard the preference and supply a default representation. The appropriate behavior depends on the field’s rules and the application’s requirements."
    },
    {
      "heading": "Caching and the Vary field",
      "text": "Content negotiation interacts closely with HTTP caching. A cache that identifies responses only by request method and target URI could otherwise serve a representation chosen for one client to another client with different preferences.\n\nThe Vary response field identifies request fields that influenced representation selection:\n\nVary: Accept-Language, Accept-Encoding\n\nFor a stored response with this field, a cache must account for the named request fields when deciding whether that response can satisfy a later request. A French compressed response cannot simply be reused for an English-only client on the basis of the URI alone.\n\nVary does not list the available variants or itself make a response cacheable. Other cache controls still apply. Vary: * prevents ordinary reuse without validation because the selection factors cannot be captured by matching a finite list of request fields.\n\nNegotiation can reduce cache efficiency when many combinations produce separate cache entries. Implementations may group equivalent preferences into a smaller set of variants, provided their cache behavior remains correct. Compression also affects validators: differently content-coded representations require distinct strong entity tags."
    },
    {
      "heading": "Uses and limitations",
      "text": "Common uses include:\n\n- Delivering translated pages according to language preferences.\n- Selecting image formats supported by a browser.\n- Serving compressed representations to reduce transmission size.\n- Offering machine-readable and human-readable views of a resource.\n- Selecting API representations through vendor-specific media types or media-type parameters.\n\nContent negotiation is not the same as responsive layout. A browser can adapt one HTML representation to different screen sizes using CSS without the server selecting different representations. Negotiation instead changes what the server sends.\n\nLanguage negotiation also has limits. Browser settings do not necessarily identify a user’s preferred language for every context, and language preference does not establish nationality or location. Explicit user choices may therefore take precedence over inferred defaults.\n\nDetailed preference headers can contribute to browser fingerprinting, creating privacy concerns. Incorrect cache configuration can deliver the wrong language, format, or coding to another client. Personalized or access-controlled content requires appropriate cache controls and cannot be protected merely by adding negotiation fields to Vary.\n\nFor stable linking, explicit selection, and predictable caching, applications sometimes use separate addresses for different languages or formats. This complements rather than necessarily replaces negotiation: a negotiated entry point can direct clients to an explicitly identified variant."
    },
    {
      "heading": "Standardization",
      "text": "Content negotiation was part of the early HTTP/1.1 standardization effort, including RFC 2068 in 1997. Its core semantics are now described in RFC 9110, published in 2022 by the Internet Engineering Task Force, while associated caching rules are specified in RFC 9111.\n\nThe semantics apply across HTTP versions. HTTP/2 and HTTP/3 change message transport and framing, but retain the fundamental distinction between a resource, its representations, client preferences, and server selection."
    }
  ],
  "links": [
    "hypertext-transfer-protocol",
    "uniform-resource-identifier",
    "metadata",
    "html",
    "data-compression",
    "world-wide-web",
    "application-programming-interface",
    "utf-eight",
    "character-encoding",
    "web-browser",
    "cascading-style-sheets",
    "data-privacy",
    "internet-engineering-task-force"
  ],
  "sources": [],
  "license": "https://creativecommons.org/licenses/by/4.0/"
}