API Versioning
API versioning lets clients and servers evolve independently by exposing explicit contract versions, so breaking changes ship without silently breaking existing callers.
Definition
API versioning is the practice of labeling a published interface with an explicit version so breaking changes can ship without breaking existing clients, while older versions are deprecated on a communicated timeline.
Context and scope
Use it when external or independently deployed clients depend on a contract you cannot update atomically, especially public APIs, partner integrations, and mobile apps.
Common misconceptions
- Every change requires a new version; only breaking changes do
- A version number guarantees compatibility; it is a promise that still needs contract tests
- A version in the URL is the only correct approach; headers and media types are valid alternatives
Anti-patterns
- Shipping v2 as a full copy of v1 instead of a thin compatibility layer
- Keeping unlimited versions alive with no deprecation date or usage telemetry
- Bumping the version for additive fields that old clients already ignore
Related concepts
Related examples
Authoritative source
How versioning works
An API version is a durable label on a contract, not on a deployment. The server routes each request to the code path that implements the requested version, and every version keeps its own validation, serialization, and documentation. When behavior must change incompatibly — removing a field, tightening validation, renaming a resource — you publish a new version, announce it, and keep the old one running until traffic drops or the deprecation window closes.
GET /v2/orders/123 HTTP/1.1
Authorization: Bearer ...Versions can also live in a header (X-API-Version: 2) or a media type (Accept: application/vnd.shop.v2+json). The transport choice affects caching and discoverability more than correctness. What matters is that exactly one version is resolved per request and logged, so remaining usage can be measured.
When to use it
Version explicitly when clients are external, cached, or updated on their own schedule: mobile apps, partner integrations, SDKs. For services deployed together, prefer additive change and compatibility tests before adding a version. Every live version is a maintenance cost — duplicated tests, backports, and documentation.
Trade-offs
Path versioning is visible and easy to route but hardcodes versions into bookmarks and analytics. Header versioning keeps URLs clean but complicates caching and manual testing. Media-type versioning is expressive yet poorly understood by many clients. All approaches need a deprecation policy with dates, Deprecation and Sunset headers, and telemetry on who still calls old versions.
Example and misconceptions
A common mistake is treating version numbers as a compatibility guarantee. A v1 that quietly changes a field type still breaks clients, which is why contract tests belong in CI.
Related concepts: Backward Compatibility, Schema Evolution, and OpenAPI Contract.