API Versioning: Strategies for Evolving APIs Without Breaking Integrations
APIs are contracts between a provider and its consumers. Changing an API without a versioning strategy breaks existing integrations — a significant disruption for clients that depend on it. API versioning allows APIs to evolve while maintaining compatibility with existing consumers.
Why Versioning Matters
Breaking changes in APIs — removing fields, changing response shapes, altering authentication — will break any integration relying on the old behaviour. Even well-intentioned improvements can have unintended impact. Versioning decouples the API's evolution from consumer upgrade cycles.
URL Versioning
The most common approach: embed the version number in the URL path. /api/v1/users and /api/v2/users are distinct endpoints with potentially different behaviour and response shapes. Simple, visible, easy to route, easy to document separately. The standard approach for public APIs.
Header Versioning
Version specified in request headers: Accept: application/vnd.api+json;version=2. Keeps URLs clean but less discoverable — the version is not visible in the URL. Used by GitHub's API and some others.
Semantic Versioning for APIs
MAJOR version changes when breaking changes are made. MINOR version for backwards-compatible additions. PATCH for backwards-compatible bug fixes. API consumers should monitor for major version changes.
Deprecation Policy
APIs should provide clear deprecation timelines — minimum 6-12 months notice for major version retirement, communicated in documentation, response headers, and direct communication to registered consumers. Deprecation without notice is hostile to API consumers.