🤝Content Negotiation

NEW

Selecting the best representation of a resource based on client preferences and server capabilities.

DESCRIPTION

Content negotiation is an HTTP mechanism where clients express preferred media types, languages, and encodings, and servers select an appropriate representation. It supports server-driven or agent-driven negotiation using headers like Accept and Accept-Language. Proper caching with Vary avoids serving mismatched representations. It simplifies APIs by keeping one URI for multiple formats (e.g., JSON, XML) and facilitating localization. Misuse can complicate caching and debugging if not transparent.

ALTERNATIVE DEFINITIONS

MDN Web Docs

Content negotiation is the mechanism that makes it possible to serve different versions of a document (or more generally, a representation) at the same URL, so that user agents can specify which version fits their capabilities the best.

Highlights one-URL, multi-representation delivery based on capabilities.

Source

IETF RFC 7231

Content negotiation is the process of selecting the best representation for a given response when there are multiple representations available.

Normative definition focusing on selection among multiple representations.

Source

RELATED TERMS

Accept Accept-Language Accept-Encoding Vary Media Type REST Hypermedia as the Engine of Application State API Versioning

COMPETING TERMS

URL-based Versioning

KNOWLEDGE AREAS

Data Integration & Interoperability Software Engineering Platform & Tooling

TARGET AUDIENCE

Software Developer Software Architect Solution Architect DevOps Engineer

EXTERNAL SOURCES

• Wikipedia - Content negotiation
• MDN Web Docs - Overview and examples of negotiation
• IETF - Accept* request header definitions

TOP QUESTIONS

How does Content Negotiation work in practice?

Clients send Accept headers specifying preferred media types, languages, or encodings; servers choose the best match and respond with Vary headers for proper caching.

Category: Overview

What’s the difference between server-driven and agent-driven negotiation?

Server-driven relies on server selection; agent-driven redirects clients to alternate representations or provides choices for the client to select.

Category: Comparison

Is Content Negotiation good for API versioning?

Media type versioning via Accept headers is common, but URL-based versioning can be simpler for caching and discoverability.

Category: Opinion

How does Vary impact caching with Content Negotiation?

Vary tells caches which request headers affect the response representation, preventing cache mismatches across clients.

Category: Caching

How do I handle unsupported media types?

Return 406 Not Acceptable or default to a widely supported type like application/json with clear documentation.

Category: BestPractice

Can Content Negotiation harm performance?

Yes, if it causes cache fragmentation or complex routing. Use limited, well-defined variants and cache-friendly strategies.

Category: Risks

What headers are involved in Content Negotiation?

Accept, Accept-Language, Accept-Charset, and Accept-Encoding shape requests; Vary and Content-Language often appear on responses.

Category: Concepts

How do I test Content Negotiation?

Use curl or HTTP clients to vary Accept headers, verify Vary handling, and confirm correct representations and cache behavior.

Category: Testing

How does Content Negotiation relate to HATEOAS?

HATEOAS focuses on hypermedia-driven navigation; content negotiation determines the representation format of those resources.

Category: Relations