API Versioning
Managing incompatible changes to an API by publishing explicit versions, so existing clients keep working while new clients get the new behavior.
Also known as: API Versions, API Version Management, API Evolution, Versioned APIs
Category: Software Development
Tags: software-development, api-design, software-architecture, compatibility, apis, maintainability
Explanation
An API is a promise to the people who build on it. Sooner or later you'll want to change that promise in a way that would break them. API versioning lets you do it without forcing every client to change on the same day: the old version keeps running, the new version appears next to it, and clients move when they're ready.
**Where to put the version**:
- **In the URL path**: `/v1/customers`. Visible, simple, easy to route and to cache. The most common choice
- **In a header or media type**: Keeps the URLs stable. Less visible, and harder to try out by hand
- **In a query parameter**: Easy to add, and easy to forget
- **Date-based versions pinned per account**: Each account stays on the version that existed when it first called the API, and upgrades explicitly. Stripe is the well-known example: internally, small compatibility layers translate between the current code and each older version
- **No versions, only evolution**: Only ever add. Mark old fields as deprecated and remove them after their usage drops to zero. GraphQL APIs often work this way
**What needs a new version**:
Only breaking changes. Adding an optional field or a new endpoint doesn't, as long as the clients ignore what they don't know (see Tolerant Reader). An API that needs a new version for every small addition has a compatibility problem, not a versioning problem.
**Good practices**:
- **Version from day one**: Adding versioning later is itself a breaking change
- **Evolve first, version last**: Each live version is code to run, test, secure and document
- **Publish a policy**: How long is a version supported? How is the end announced? (see Deprecation)
- **Measure usage per version**: You can only retire what you can see
- **Keep the old versions thin**: Translate old requests to the current model at the edge, instead of keeping whole copies of the system alive
- **Describe the differences**: A changelog and a migration guide for each version
**For libraries**:
Semantic Versioning plays the same role: the major version number announces a breaking change.
**The trade-off**:
Versioning moves the cost of change from the consumers to the provider. Too few versions, and you break people. Too many, and you maintain all of them forever.
Related Concepts
← Back to all concepts