APIintermediate

Content Negotiation

The HTTP mechanism where clients specify preferred response formats via the Accept header and servers respond with appropriate Content-Type.

Also known as: Accept Header, Media Type Negotiation

Description

Content negotiation is the HTTP mechanism that allows clients and servers to agree on the format of exchanged data. The client sends an Accept header indicating which media types it can handle (e.g., Accept: application/json, application/xml;q=0.9), and the server selects the best match from the formats it supports. The server then responds with the chosen format and sets the Content-Type header accordingly. If no acceptable format is available, the server returns 406 Not Acceptable.

In modern APIs, JSON is almost universally the default format, but content negotiation becomes important for APIs that support multiple formats (JSON, XML, CSV, Protocol Buffers), versioning via media types (Accept: application/vnd.myapp.v2+json), or specialized representations (Accept: application/hal+json for HATEOAS). Request body format is communicated via the Content-Type header, and the server should validate that the request Content-Type matches what it can parse, returning 415 Unsupported Media Type if not.

Beyond format negotiation, HTTP supports language negotiation (Accept-Language), encoding negotiation (Accept-Encoding for gzip/br compression), and character set negotiation. For APIs, compression negotiation is particularly important for performance: supporting gzip and Brotli compression can reduce response sizes by 70-90% for JSON payloads, significantly improving latency on high-bandwidth endpoints.

Prompt Snippet

Default to application/json but support content negotiation via the Accept header. Return 406 Not Acceptable if the client requests an unsupported media type. Validate the request Content-Type header and return 415 Unsupported Media Type for unrecognized types. Support API versioning via vendor media types (Accept: application/vnd.gapcheck.v2+json) as an alternative to URL path versioning. Enable gzip and Brotli compression at the reverse proxy layer (NGINX: gzip_types application/json) and verify Accept-Encoding handling with integration tests.