Notesencoding🌱 seedling
API Versioning
Also: API Version · Versioned API · Version Pinning · Breaking Change · Dated Versioning
API versioning lets a service make breaking changes without breaking clients it doesn't control, by letting each client keep the version it was built against. Additive changes need no version, as long as clients ignore unknown fields.
Why it exists
Public API clients upgrade on their own schedule, or never. The server must keep serving every shape it ever promised, for years.
How it works
- Additive, no version needed: new endpoints, optional parameters, new response fields.
- URL major versions (
/v1/,/v2/): simple and visible, but each version is effectively a separate API to maintain. - Dated versions in a header: GitHub's
X-GitHub-Api-Version(first version2022-11-28; an old version stays supported for at least 24 months after a newer one ships). - Pinning + transformation (Stripe): an account is pinned to the version current at its first request;
Stripe-Versionoverrides per request; core code builds the latest response and it is walked back through one version change module per breaking change.
Trade-offs
| Approach | Gains | Costs |
|---|---|---|
| URL major version | obvious, cache-friendly | big-bang migrations, parallel codebases |
| dated header | small, frequent changes | clients must send it; support windows to manage |
| pin + transform modules | old versions isolated from core code | transformation layer to build and test |
In practice
- Stripe handled almost a hundred backward-incompatible changes in six years this way (as of 2017), keeping every version since 2011 working. Since
2024-09-30.acaciait ships monthly non-breaking versions and twice-yearly major releases.
Pitfalls
- Clients that fail on unknown fields or enum values: then even additive changes break them.
- Webhooks and events need versioning too, not just request/response.
Connections
- Part of
- Encoding
- Learn first
- Backward and Forward Compatibility
Recall
These cards are also in your review deck, scheduled with spaced repetition.