Content Negotiation

The Core Mechanism: Accept Headers

Content negotiation is fundamentally driven by the client's 'Accept' header, which signals the media types the client is prepared to handle. Instead of hardcoding a specific format into the URL, such as /user/1.json, the server inspects the 'Accept' header provided in the HTTP request. This architectural decision decouples the resource identity from its representation. The server acts as a translator, determining the best possible match from the client's list of acceptable formats and the formats the server actually supports. If a client requests a type that the server cannot provide, the server must respond with a 406 Not Acceptable status code. This approach ensures that a single URL remains clean and semantic, adhering to the REST principle that a URI identifies a resource, not the format of that resource, thereby improving cacheability and long-term system maintainability significantly.

GET /api/products/123 HTTP/1.1
Accept: application/json, application/xml

# The server parses the Accept header to decide format
# If it prefers JSON, it sets Content-Type: application/json

Server-Driven Selection

In server-driven negotiation, the server is the final arbiter of which representation to return. When a request arrives, the server evaluates the 'Accept' header against its own capabilities. This logic is usually implemented by looking at the quality values, or 'q-values', which allow clients to rank their preferences numerically from 0 to 1. If a client sends 'Accept: application/json;q=0.9, text/html;q=0.8', the server will prioritize JSON. By shifting the decision to the server, you gain central control over the responses delivered to the client ecosystem. This is critical when you need to deprecate older formats or introduce newer, more efficient serialization methods without forcing every client to update their request URL. It forces the server to be intelligent, ensuring it can handle various incoming header permutations gracefully while maintaining consistent business logic across different media types.

if request.headers.get('Accept') == 'application/xml':
    # Convert resource to XML format before sending
    return serialize_to_xml(data), 200, {'Content-Type': 'application/xml'}
else:
    # Default to JSON as it is the standard
    return serialize_to_json(data), 200, {'Content-Type': 'application/json'}

Content-Type and Request Bodies

While the 'Accept' header handles responses, the 'Content-Type' header governs request bodies sent by the client. It informs the server precisely how to parse the incoming data. Without this header, a server would have to blindly attempt to guess the encoding or structure of the payload, which is fragile and prone to security vulnerabilities. By requiring a 'Content-Type', the server can safely delegate the parsing to specialized modules. For instance, if the client sends a POST request with 'Content-Type: application/json', the server uses its JSON parser. If the type is missing or unsupported, the server should return a 415 Unsupported Media Type status code. This strict contract between client and server ensures that the payload is interpreted correctly, preventing corruption and ensuring that the data processed matches the expected schema defined by the API contract.

POST /api/products HTTP/1.1
Content-Type: application/json

{"name": "Gadget", "price": 29.99} 
# Server checks Content-Type header to choose correct deserializer

Vary Header for Caching

When using content negotiation, standard HTTP caching becomes more complex because a single URL can now map to multiple representations. To prevent an intermediary cache, like a CDN, from serving a JSON response to a client that requested XML, the server must include the 'Vary' header in its response. The 'Vary: Accept' header instructs caches that the response is dependent on the 'Accept' header value provided in the request. This ensures that caches store unique versions for each representation, preventing the serving of cached data that the client cannot actually interpret. Without the 'Vary' header, you risk delivering broken payloads to users, defeating the purpose of efficient content delivery. Proper usage of 'Vary' is a cornerstone of building scalable and reliable distributed systems where performance and data integrity are equally prioritized by the architecture.

# Response headers must include Vary to ensure correct caching
headers = {
    'Content-Type': 'application/json',
    'Vary': 'Accept'  # Tells caches to differentiate by Accept header
}
return response, 200, headers

Language Negotiation

Content negotiation extends beyond serialization formats into locale and language preferences via the 'Accept-Language' header. Just as a client can request JSON or XML, they can indicate their preference for a specific human language, such as 'en-US' or 'fr-FR'. The server uses this header to determine which translated string resources should be injected into the response body. This is a powerful pattern for globalized applications, allowing the same endpoint to serve a localized experience without requiring language-specific URLs. The logic remains consistent: check the client's preference, compare it against your supported translations, and provide the best available match. If no match exists, fall back to a default language. This keeps your URI space uncluttered while providing a rich, personalized experience, demonstrating the extreme versatility of header-based negotiation in modern software design.

lang = request.headers.get('Accept-Language', 'en')
# Select the message based on the requested language
message = localized_strings.get(lang, 'Hello')
return {'message': message}, 200, {'Content-Language': lang}

Interview questions

All REST API Design interview questions →

Check yourself

Take the full REST API Design quiz →