API versioning
Giving an API contract explicit versions so consumers can upgrade on their own schedule, and retiring old versions with notice.
Adding an optional field rarely breaks anyone; renaming a field, changing its meaning or removing it does. Versioning makes breaking changes explicit: a version in the URL (/v2/), a header, or a dated version pinned per client, as Stripe does, with old versions translated to the current code by a compatibility layer. Inside one organization, events and internal APIs need the same discipline once another team depends on them.
Retiring a version is part of the design. The HTTP Deprecation and Sunset headers tell clients when a version is deprecated and when it will stop working. Many changes can avoid a new version entirely with expand and contract, and consumer-driven contracts show who still uses what.
Sources
- Stripe: APIs as infrastructure: future-proofing Stripe with versioning stripe.com
- RFC Editor: RFC 9745: The Deprecation HTTP Response Header Field rfc-editor.org
- RFC Editor: RFC 8594: The Sunset HTTP Header Field rfc-editor.org
Related terms
- Expand and contract (zero-downtime migrations): Changing a database schema in backward-compatible steps: add the new shape, migrate code and data, and remove the old shape only later.
- Consumer-driven contracts (contract testing): Each consumer of an API writes down what it actually uses, and the provider’s build checks every change against those expectations before release.
- Open host service (published language): An upstream context offers one documented, stable protocol for all consumers instead of a custom integration for each, often with a published data format.
- Customer-supplier (upstream and downstream): A relationship between two teams where the upstream team plans its changes with the needs of the downstream team that depends on it.
- Tolerant reader: A consumer of an API or event reads only the fields it needs and ignores everything else, so the provider can add fields without breaking it.
