API versioning is the discipline of evolving a programmatic interface over time while controlling the impact of changes on existing consumers. It defines how new versions are identified, published, and retired, and how backward compatibility is preserved or broken deliberately. Sound versioning lets providers innovate without forcing every client to upgrade in lockstep.
Overview
- Versioning strategies trade off clarity, routing complexity, and client burden. Common approaches encode the version in the URI path, in a request header, in a media type (content negotiation), or in a query parameter. Providers distinguish non-breaking changes — additive fields, new optional parameters — which can ship without a new version, from breaking changes that require one. A mature lifecycle pairs versioning with a deprecation policy: communicating sunset dates, supporting old versions for a defined window, and routing requests through an API gateway that can translate or shield clients during transitions.
Key aspects
- Version identification: URI path, header, media-type, or query-parameter schemes for selecting a version.
- Compatibility classification: distinguishing additive non-breaking changes from breaking changes.
- Semantic versioning: major.minor.patch conventions that signal the nature of a change to consumers.
- Deprecation and sunsetting: announcing, supporting, and eventually retiring superseded versions on a schedule.
- Contract documentation: machine-readable specifications such as OpenAPI that pin each version’s contract.
Applications
- Evolving public REST and GraphQL APIs without breaking third-party integrations.
- Coordinating independent deployment of microservices behind stable contracts.
- Managing platform and partner ecosystems with long client lifecycles.
- Gateway-mediated migration between major API versions.