API Versioning
API versioning is the practice of managing change in a public API so that existing consumers continue to work as new features or breaking changes are introduced; URL path versioning embeds the version in the path (for example, /v1/users vs; Versioning strategy is an early architectural decision with long-term consequences
API versioning is the practice of managing change in a public API so that existing consumers continue to work as new features or breaking changes are introduced. Without versioning, any breaking change requires all consumers to update simultaneously, which is impractical for widely-used APIs.
How it works
URL path versioning embeds the version in the path (for example, /v1/users vs. /v2/users), making the version explicit and easy to route. Header-based versioning uses an Accept header or custom header (for example, API-Version: 2024-01-01) to select behavior. Date-based versioning, popularized by Stripe, uses a release date as the version identifier.
Key facts
- URL versioning: Most discoverable approach; makes version explicit in every request
- Sunset header: RFC 8594 defines the Sunset header for communicating deprecation dates to consumers
- Deprecation period: Best practice is to maintain old versions for at least 6-12 months after announcing deprecation
For builders
Versioning strategy is an early architectural decision with long-term consequences. Building a deprecation and sunset process alongside the versioning scheme prevents the accumulation of unmaintained API versions.
Sources
- IETF. RFC 9110: HTTP Semantics. datatracker.ietf.org
- IETF. RFC 9112: HTTP/1.1. datatracker.ietf.org
- Fielding, R. (2000). Architectural Styles and the Design of Network-based Software Architectures (REST). UC Irvine. ics.uci.edu
- OWASP. API Security Top 10 (2023). owasp.org
- MDN Web Docs. HTTP reference. developer.mozilla.org
