Content Negotiation
Subject: Computer and Technology noun /ˈkɑːn.tɛnt nɪˌɡoʊ.ʃiˈeɪ.ʃən/ 1 definition
- web-development
- network-protocols
- web-standards
- computer-networking
-
Definition (noun)
Entry #319 · UpdatedContent Negotiation is an HTTP mechanism that enables a client and server to select the most suitable representation of a resource served at a single Uniform Resource Identifier (URI). Rather than exposing separate endpoints for every data format, compression algorithm, or locale, the parties negotiate across dimensions such as media type, character encoding, and natural language using request headers—including
Accept,Accept-Language, andAccept-Encoding—or server-supplied variant lists. Based on those signals and optional quality (q) weights, the server selects or transforms the matching variant, describes it using response headers likeContent-Type,Content-Encoding, andContent-Language, and includes aVaryheader so shared caches key variants accurately. By decoupling a resource's stable logical identity from its concrete wire representation, content negotiation supports API evolution, compression, and localization without multiplying routes, though omittingVaryheaders can cause caches to serve mismatched variants and strict matching can trigger406 Not Acceptableerrors.Common Forms
Server-Driven (Proactive) Negotiation: The client attaches preference headers such as
Accept,Accept-Language, andAccept-Encodingwith optionalq-factor weights, allowing the server to pick and return the optimal variant in a single round trip.Agent-Driven (Reactive) Negotiation: The server returns metadata describing available variants—commonly via a
300 Multiple Choicesor406 Not Acceptableresponse—so the client can inspect the options and issue a follow-up request for a specific representation.Transparent Content Negotiation: An intermediate proxy or cache retrieves a variant list from the origin server and negotiates representation selection directly with the client, reducing upstream round trips while preserving preference matching.
URI-Driven (Suffix or Parameter) Negotiation: Web frameworks emulate content negotiation by mapping path extensions (such as
/invoices.csv) or query parameters (?format=xml) to specific serializers, trading strict single-URI purity for shareable links when custom request headers are impractical.
Example
When a billing client sends
GET /v2/invoices/8492over HTTPS withAccept: application/json;q=1.0, application/xml;q=0.5andAccept-Encoding: zstd, gzip, the API server evaluates those preferences against its supported serializers and compressors in one round trip. Finding JSON and Zstandard available, it responds with200 OK,Content-Type: application/json,Content-Encoding: zstd, andVary: Accept, Accept-Encodingso downstream CDN caches never serve a Zstandard-compressed JSON payload to a client requesting uncompressed XML.