ContentNegotiation

Content negotiation is a mechanism in HTTP that allows a client and server to agree on a representation of a resource based on client capabilities and preferences. It enables the same resource to be delivered in different formats, languages, encodings, or character sets. The client communicates its preferences through request headers such as Accept, Accept-Language, Accept-Encoding, and Accept-Charset, optionally assigning quality values (q) to express relative priorities, for example text/html;q=0.9, application/json;q=0.8. The server provides a set of available representations and selects the best match.

During processing, the server compares the client’s preferences with the available variants and chooses the most appropriate one. If a matching variant exists, the server returns it with a 200 status. If no acceptable variant is available, the server may respond with a 406 Not Acceptable, or occasionally fall back to a default representation. Content negotiation can be server-driven or transparent, and is described in HTTP specifications and related standards documents.

A response may vary based on the request headers, so the Vary header is used to inform caches that the content depends on certain headers, such as Accept or Accept-Language. This helps caches store separate variants to avoid delivering inappropriate representations.

Common use cases include serving HTML or JSON from an API, providing content in multiple languages, or selecting compressed encodings such as gzip. While content negotiation can simplify resource maintenance, it adds caching and implementation complexity, so many services opt for explicit or URL-based variant selection to reduce ambiguity.