Meaning
Header versioning is an API versioning strategy where the API version is communicated through HTTP request or response headers rather than in the URL path or query string. It addresses the need to keep URLs clean and stable while still allowing clients to negotiate which version of the API they receive. This approach is triggered when designing REST APIs where URL aesthetics, caching behavior, or content negotiation semantics matter.
Primary Function
API design
Communicative Purpose
Enables clients to request specific API versions through HTTP headers while keeping resource URLs stable and cache-friendly.
Pattern
client sends Accept or X-API-Version header → server routes to versioned handler → response served with version metadata
Função primária
API design
Propósito comunicativo
Enables clients to request specific API versions through HTTP headers while keeping resource URLs stable and cache-friendly.
Situações de gatilho
REST API design: choosing a versioning strategy for a public API; API gateway configuration: routing requests based on Accept or custom version headers; Backward compatibility: introducing breaking changes without altering URL structure
Contextos
REST APIs, HTTP services, API gateways, microservices, public API platforms
Padrão
client sends Accept or X-API-Version header → server routes to versioned handler → response served with version metadata
Colocados típicos
- Accept header
- content negotiation
- vendor media type
- API gateway
- X-API-Version
- version routing
Substituições comuns
- URL path versioning (/v1/resource) — more visible and cacheable but pollutes URLs
- Query parameter versioning (?version=2) — simple but harder to cache
- Subdomain versioning (v1.api.example.com) — strong isolation but DNS overhead
Erros comuns
Using a custom header without documenting it — clients have no way to discover the versioning mechanism; Forgetting to set a default version when the header is missing — server crashes or returns wrong version; Treating header versioning as truly RESTful when it conflicts with HTTP caching — intermediaries may not vary cache by custom headers
Similar / contraste
URL path versioning — version embedded in path; Content negotiation — broader mechanism for media type selection; API key versioning — versioning the credential rather than the contract
Interferências
Coming from SOAP/WSDL: may assume versioning is always in the envelope namespace — REST header versioning is a different negotiation model; Coming from GraphQL: may think versioning is unnecessary because of schema evolution — REST APIs still need explicit version contracts
Família do chunk
- URL path versioning
- query parameter versioning
- content negotiation
- API versioning strategies
Nuance
When NOT to use: when clients are browser-based and cannot easily set custom headers without CORS preflight; Performance: header-based routing adds slight overhead at the gateway but avoids URL parsing; Boundary condition: intermediaries may strip or normalize non-standard headers, breaking versioning silently
Efeito pragmático
Keeps URLs stable across versions, supports content negotiation semantics, and allows fine-grained version control at the gateway level without exposing version info in shared links.
Dica de memória
Header versioning is like ordering coffee by telling the barista your preference instead of pointing at a labeled menu item — the resource stays the same, but the version is negotiated through a side channel.
Upgrade path
Content negotiation with vendor media types and hypermedia-driven versioning
Log in to save chunks.