Skip to content
Velloreth
Programming 5 min read

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

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:

  1. Announce the deprecation and the date.
  2. Add the headers, so the migration is visible in a client’s log.
  3. Monitor the usage of the old version.
  4. Remind the remaining clients.
  5. 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 Deprecation and a Sunset header.
  • 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.

Frequently asked questions

What is a breaking change in an API?
A change that breaks an existing client, such as removing a field, renaming one, changing a type, or making an optional parameter required.
What is the difference between URL and header versioning?
URL versioning puts the version in the path, such as /v1/users, which is visible and easy to route. Header versioning puts it in a header, which keeps the URL clean but is harder to test and cache.
Is adding a field a breaking change?
No, if the client ignores an unknown field. It is breaking if the client validates strictly against a schema, which is why a client should be tolerant.
How long should I support an old version?
Long enough for the clients to migrate, which depends on who they are. A public API needs months; an internal one may need days.
What is a deprecation header?
A response header such as Deprecation or Sunset that tells the client the endpoint is going away and when, so the migration is visible in a log.
Should I version a GraphQL API?
GraphQL usually evolves without a version, by adding a field and deprecating an old one, because the client asks for exactly the fields it needs.