API Versioning Strategies Compared
URL, header and media-type versioning each break a client differently. Learn the trade-offs and how to make a change without a new version.
By Velloreth
What a version is
A version is a promise about compatibility.
It says: a client written against this version will keep working.
The cost: every version must be maintained, tested, and documented.
The rule that follows: add a version only when a breaking change is unavoidable, and make an additive change without one.
What is breaking
Breaking:
- Removing a field.
- Renaming a field.
- Changing a type, such as a number to a string.
- Making an optional parameter required.
- Changing the meaning of a value.
- Changing the default of a parameter.
- Removing an endpoint.
- Changing an error code.
Not breaking:
- Adding a new field.
- Adding a new endpoint.
- Adding an optional parameter.
- Adding a new enum value, if the client handles an unknown one.
The last one is a trap. Adding an enum value is not breaking in theory, and it breaks a client that switches on the value without a default case.
URL versioning
GET /v1/users
GET /v2/users
The advantage: it is visible, it is easy to route, and it is easy to test with curl.
The disadvantage: the version is in every URL, and a resource that exists in both versions has two addresses.
This is the most common choice, and it is the pragmatic one. Stripe, GitHub, and Twilio all use a variant of it.
A major version only. /v1 and /v2, not /v1.2.3. A minor version is a documentation concern, not a routing one.
Header versioning
GET /users
Accept-Version: 2
The advantage: the URL is clean, and the resource has one address.
The disadvantage: it is invisible in a browser, harder to test, and it complicates caching, because the response depends on a header and the cache needs a Vary.
A custom header is the common form. A media type is the purist form:
Accept: application/vnd.example.v2+json
The media-type approach is the most correct by the REST definition, and it is the least practical, because it is awkward in a browser and in a tool.
Query parameter versioning
GET /users?version=2
The advantage: it is easy to add and easy to test.
The disadvantage: it is easy to forget, and a missing parameter silently falls back to a default version.
It is rarely the right choice, though it is a reasonable escape hatch for a single endpoint.
Date-based versioning
Stripe-Version: 2026-10-26
The version is a date, and the client pins the date it was written against.
The advantage: a change is opt-in per client, and a new client gets the latest behaviour.
The disadvantage: it requires a compatibility layer that transforms the response per version, which is a significant engineering investment.
Stripe does this, and it is the most client-friendly model, and the most expensive to build.
Evolving without a version
Most changes do not need a version.
Add a field. A tolerant client ignores it.
Add an endpoint. Nothing breaks.
Add an optional parameter. The default preserves the old behaviour.
Deprecate a field rather than removing it, and keep it for a release cycle.
The practical approach: version the API once, at /v1, and evolve it additively for as long as possible. Add /v2 only when a breaking change is genuinely required.
Deprecation
A deprecation needs a timeline.
Deprecation: true
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"
Deprecation marks the endpoint as deprecated.
Sunset gives the date it will be removed.
Link points at the replacement.
The process:
- Announce the deprecation and the date.
- Add the headers, so the migration is visible in a client’s log.
- Monitor the usage of the old version.
- Remind the remaining clients.
- Remove it after the date.
The monitoring step is the important one. Without it, the removal breaks a client that nobody knew about.
Versioning and the client
The cost of a version falls on the client, and the way the version is expressed determines how much work a migration is. A URL version is the easiest to migrate, because the change is a string in a configuration file, and it is the easiest to test, because the old and the new can be called side by side. A header version is harder, because the change is in a client library or an interceptor, and it is invisible in a log unless the header is recorded. A date-based version is the hardest to implement on the server and the easiest for the client, because the client pins a date and the server does the transformation. The practical advice is to choose the model that matches the audience: a public API with many unknown clients benefits from a date-based version and a long support window, while an internal API with a handful of known clients is fine with a URL version and a short one.
Practical guidance
- Version only for a breaking change.
- Use a major version only.
- Prefer URL versioning for a public API.
- Evolve additively as long as possible.
- Deprecate rather than remove.
- Add a
Deprecationand aSunsetheader. - Monitor the usage of an old version.
- Document the compatibility promise.
- Make the client tolerant of an unknown field.
For the related guides, see rest-api-design-principles and api-error-responses-guide. For the broader context, semantic-versioning-explained and api-pagination-patterns.
Quotable summary
A version is a promise about compatibility, so it should be added only when a breaking change is unavoidable, and an additive change such as a new field or a new endpoint does not need one. URL versioning is the most visible and the easiest to route and it is the most common choice, while a header version is cleaner in theory and harder to test and cache in practice because the response depends on a header. A breaking change is a removed or renamed field, a changed type, or a newly required parameter, and adding an enum value is a trap because it breaks a client that switches on the value without a default case. A deprecation needs a timeline, a warning header, and a migration path, and the monitoring step is the important one because without it the removal breaks a client that nobody knew about.