Content negotiation

API Design

Meaning

Content negotiation is the HTTP mechanism where client and server agree on the best representation of a resource based on request headers. It solves the problem of serving multiple formats, languages, or encodings from a single endpoint without requiring separate URLs for each variant. Triggered when an API must support diverse clients with different content, language, or encoding preferences.

Primary Function

API design

Communicative Purpose

Enables a single endpoint to serve multiple representations tailored to client capabilities and preferences without proliferating URLs.

Pattern

client sends Accept-* headers → server selects best match → returns chosen representation with matching Content-Type

Função primária

API design

Propósito comunicativo

Enables a single endpoint to serve multiple representations tailored to client capabilities and preferences without proliferating URLs.

Situações de gatilho

REST API design: serving JSON, XML, or HTML from one URL based on the client's Accept header

Contextos

REST APIs, HTTP web services, content delivery networks, multilingual web platforms, microservice gateways

Padrão

client sends Accept-* headers → server selects best match → returns chosen representation with matching Content-Type

Colocados típicos

Accept header
Vary header
q-value weighting
406 Not Acceptable
media type
Content-Type
Accept-Language
Accept-Encoding

Substituições comuns

URL-based versioning (/api/v1/
/api/v2/): simpler but proliferates endpoints and breaks link stability

Erros comuns

Forgetting the Vary header: cache returns wrong content-type to clients with different Accept headers, causing cache poisoning

Similar / contraste

API versioning: changes the interface contract itself rather than the representation format of a single resource

Interferências

Coming from SOAP/WSDL: may assume rigid contract binding — REST content negotiation is more flexible and client-driven via headers

Família do chunk

HTTP headers
Accept header
Vary header
media types
content types
API versioning
q-values

Nuance

When NOT to use: simple internal APIs with one client type where the parsing overhead exceeds the benefit of format flexibility

Efeito pragmático

Allows one API endpoint to serve diverse clients (mobile, web, partners) with format-appropriate responses, reducing endpoint proliferation and simplifying client integration across locales and capabilities.

Dica de memória

Like a restaurant that asks 'any allergies or preferences?' before serving — the kitchen (server) tailors the dish to what the diner (client) signals it can accept.

Upgrade path

Implement q-value parsing for weighted Accept headers and distinguish server-driven from agent-driven negotiation strategies

Frequência: MediumFormulaicidade: FlexiblePrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

from flask import Flask, request, Response import json app = Flask(__name__) @app.route('/api/user/<int:user_id>') def get_user(user_id): user = {"id": user_id, "name": "Alice", "email": "alice@example.com"} accept = request.headers.get('Accept', '*/*') if 'application/xml' in accept: xml = f'<user><id>{user["id"]</id><name>{user["name"]</name</user>' return Response(xml, mimetype='application/xml') elif 'application/json' in accept or '*/*' in accept: return Response(json.dumps(user), mimetype='application/json') else: return Response(status=406)

package main import ( "encoding/json" "encoding/xml" "net/http" ) type Product struct { ID int `json:"id" xml:"id"` Name string `json:"name" xml:"name"` Price float64 `json:"price" xml:"price"` } func handler(w http.ResponseWriter, r *http.Request) { product := Product{ID: 1, Name: "Widget", Price: 9.99} accept := r.Header.Get("Accept") w.Header().Set("Vary", "Accept") switch { case accept == "application/xml": w.Header().Set("Content-Type", "application/xml") xml.NewEncoder(w).Encode(product) default: w.Header().Set("Content-Type", "application/json") json.NewEncoder(w).Encode(product) } } func main() { http.HandleFunc("/product", handler) http.ListenAndServe(":8080", nil) }