Accept-Version header versioning

API Design

Meaning

Accept-Version header versioning is an API versioning strategy where clients declare the desired API version through a custom HTTP header (commonly `Accept-Version` or `X-API-Version`) rather than embedding it in the URI. It addresses the pain point of evolving API contracts without breaking existing clients by allowing per-request version negotiation. This approach is triggered when designing REST APIs that need backward-compatible evolution while keeping resource URIs clean and stable.

Primary Function

API versioning

Communicative Purpose

Enables backward-compatible API evolution by letting clients declare the target version in a request header, keeping URIs free of version segments.

Pattern

client sends Accept-Version: <version> → server routes to version-specific handler

Função primária

API versioning

Propósito comunicativo

Enables backward-compatible API evolution by letting clients declare the target version in a request header, keeping URIs free of version segments.

Situações de gatilho

REST API design: evolving endpoints while preserving existing client integrations API gateway configuration: routing requests to version-specific backends based on header value Public API maintenance: deprecating old versions while supporting a migration window

Contextos

REST APIs, microservices, public API platforms, API gateways, web service backends

Padrão

client sends Accept-Version: <version> → server routes to version-specific handler

Colocados típicos

API gateway
content negotiation
version routing middleware
deprecation policy
backward compatibility

Substituições comuns

URL path versioning (/v1/users) — more visible and cache-friendly but pollutes resource identity Query parameter versioning (?version=1) — easy to add but mixes versioning with filtering concerns Media type versioning (Accept: application/vnd.api+json
version=2) — standards-aligned but verbose

Erros comuns

Forgetting to define behavior when the header is missing — causes routing to an undefined handler or 500 errors Using Accept-Version for breaking changes without a deprecation timeline — leaves clients stranded with no migration path Treating header versioning as cache-transparent — intermediaries may serve stale responses across versions Mixing Accept-Version with path versioning inconsistently across endpoints — confuses clients about which mechanism to use

Similar / contraste

URL path versioning: version is visible in URI, easier to debug but breaks resource identity Media type versioning: uses standard Accept header, more RESTful but verbose Query parameter versioning: simplest to implement but not cache-friendly

Interferências

Coming from URL-based versioning: may forget to inspect headers in middleware — Accept-Version requires explicit header parsing before route resolution

Família do chunk

URL path versioning
query parameter versioning
media type versioning
API gateway routing

Nuance

When NOT to use: public APIs with broad client bases where header inspection is unreliable (mobile apps behind proxies that strip custom headers) Performance: adds a header parse step per request, negligible but matters in high-throughput gateways Boundary conditions: missing-header behavior must be explicitly defined (default version vs. 400 error)

Efeito pragmático

Allows API providers to ship breaking changes behind a versioned contract while keeping existing clients operational, reducing forced migration pressure and enabling gradual rollouts.

Dica de memória

Like a hotel reservation where guests state their check-in date in the booking header rather than the URL — the room number stays stable, but the service tier adapts to the declared version.

Upgrade path

Media type versioning (Accept: application/vnd.api+json;version=2) — standards-aligned content negotiation

Frequência: MediumFormulaicidade: FlexiblePrioridade de aquisição: Recognition firstPrioridade de output: InputTag de espaçamento: Medium-term

Examples

from flask import Flask, request, jsonify app = Flask(__name__) @app.route('/users', methods=['GET']) def list_users(): version = request.headers.get('Accept-Version', '1') if version == '1': return jsonify([{'id': 1, 'name': 'Alice'}]) elif version == '2': return jsonify([{'id': 1, 'name': 'Alice', 'email': 'alice@example.com'}]) return jsonify({'error': 'Unsupported version'}), 400

import requests response = requests.get( 'https://api.example.com/users', headers={'Accept-Version': '2'} ) print(response.json())

const express = require('express'); const app = express(); function versionRouter(req, res, next) { const version = req.headers['accept-version'] || '1'; if (version === '1') return require('./v1/routes')(req, res, next); if (version === '2') return require('./v2/routes')(req, res, next); res.status(400).json({ error: 'Unsupported API version' }); } app.use('/users', versionRouter);