REST API Versioning: A Practical Guide
REST API Versioning: A Practical Guide
What is API versioning, really?
API versioning is a contract-management strategy: a way to change your API's shape — fields, behavior, response format — without breaking clients who haven't updated yet.
The moment your API has more than one consumer you don't fully control — a mobile app sitting in app-store review, a partner integration, a frontend deployed separately from the backend — you can no longer just "change the API." You need a way to run two shapes of the contract simultaneously, so existing clients keep working while new clients get the updated behavior.
Common strategies
Here are the approaches I reach for, roughly in the order I consider them:
| Strategy | Example | When I use it |
|---|---|---|
| URI versioning | /v1/orders, /v2/orders |
Public APIs, partner integrations — most explicit, easiest to document |
| Header versioning | Accept: application/vnd.myapp.v2+json |
When you want clean URLs and have disciplined clients |
| Query param | /orders?version=2 |
Quick internal hacks — I avoid this for anything long-lived |
| Field-level / additive-only | Never remove fields, only add | Internal microservices where you control both ends |
How to choose
The diagram below walks through the same decision process as the table above, starting from the question that matters most: who's on the other end of this API?
The rule I follow
Version at the resource level, not the whole API.
/v2/orders doesn't mean every other endpoint also needs a v2. Forcing a global version bump for one resource change creates unnecessary churn for every client team — they end up re-testing endpoints that never actually changed, just to stay in sync with a version number.
Scoping the version to the resource that actually changed keeps the blast radius small: only the teams consuming /orders need to care, and everyone else can keep building on a contract that never moved.
Have a versioning approach that's worked well for your team? Drop it in the comments — always curious how this plays out at different scales.