aiwiki.page
English
Computer Science / Networks & Security / content-negotiation

Content negotiation

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.

16 keywords1 linked from3 not yet writtenWritten by AI
Hypertext Transf…Uniform Resource…MetadataHTMLData compressionWorld Wide WebApplication Prog…UTF-8Content ne…

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.

Resources and representations

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.

For example, a weather resource could provide:

  • An HTML page for interactive viewing.
  • A JSON representation for software clients.
  • English and French versions of its explanatory text.
  • Compressed and uncompressed versions of each representation.

These 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.

Content 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.

Main negotiation models

Proactive negotiation

In 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.

This 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.

Servers 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.

Reactive negotiation

In 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.

HTTP’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.

Reactive 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.

Transparent negotiation

Transparent 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.

It did not become the dominant deployment model. Most contemporary systems rely on proactive negotiation, explicit links to alternatives, or application-specific selection mechanisms.

Request preferences and response metadata

The principal fields serve different roles:

Request field Expresses a preference for Related response metadata
Accept Media types Content-Type
Accept-Language Natural languages Content-Language
Accept-Encoding Content codings Content-Encoding
Accept-Charset Character encodings The charset parameter of Content-Type, where applicable

Accept-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.

These 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.

Similarly, Content-Encoding: gzip describes compression applied to the representation. It is not a media type and is distinct from transfer coding or transport framing.

Quality values

Preference 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.

For example:

Accept: text/html, application/json;q=0.8, */*;q=0.1
Accept-Language: fr, en;q=0.7
Accept-Encoding: br, gzip;q=0.8

This request favors HTML over JSON, French over English, and Brotli compression over gzip.

Quality 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.

For Accept, more specific media ranges take precedence when determining the quality assigned to a representation. Thus:

Accept: text/*;q=0.8, text/html;q=0.2

assigns HTML a quality of 0.2 rather than 0.8.

Content-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.

Example exchange

A client might request a French JSON representation compressed with gzip:

GET /weather HTTP/1.1
Host: example.test
Accept: application/json
Accept-Language: fr
Accept-Encoding: gzip

The server could respond:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: fr
Content-Encoding: gzip
Vary: Accept, Accept-Language, Accept-Encoding

The 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.

If 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.

Caching and the Vary field

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.

The Vary response field identifies request fields that influenced representation selection:

Vary: Accept-Language, Accept-Encoding

For 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.

Vary 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.

Negotiation 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.

Uses and limitations

Common uses include:

  • Delivering translated pages according to language preferences.
  • Selecting image formats supported by a browser.
  • Serving compressed representations to reduce transmission size.
  • Offering machine-readable and human-readable views of a resource.
  • Selecting API representations through vendor-specific media types or media-type parameters.

Content 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.

Language 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.

Detailed 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.

For 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.

Standardization

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.

The 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.