Skip to main content
Definition Website Computer and Technology

Content Negotiation

Subject: Computer and Technology noun /ˈkɑːn.tɛnt nɪˌɡoʊ.ʃiˈeɪ.ʃən/ 1 definition

  1. Definition (noun)

    Entry #319 · Updated

    Content 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, and Accept-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 like Content-Type, Content-Encoding, and Content-Language, and includes a Vary header 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 omitting Vary headers can cause caches to serve mismatched variants and strict matching can trigger 406 Not Acceptable errors.

    Common Forms

    • Server-Driven (Proactive) Negotiation: The client attaches preference headers such as Accept, Accept-Language, and Accept-Encoding with optional q-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 Choices or 406 Not Acceptable response—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/8492 over HTTPS with Accept: application/json;q=1.0, application/xml;q=0.5 and Accept-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 with 200 OK, Content-Type: application/json, Content-Encoding: zstd, and Vary: Accept, Accept-Encoding so downstream CDN caches never serve a Zstandard-compressed JSON payload to a client requesting uncompressed XML.