A Short Guide to API Versioning

Versioning is insurance against breaking the people who depend on your API. Like insurance, you want enough and not more, and you want to have set it up before you need it.

Add versioning before you have a second consumer

The first API has one caller, often your own front end, and versioning feels like ceremony. Add it anyway, as a /v1 in the path, from the start. Retrofitting a version scheme once external clients exist is far more work than typing it once at the beginning.

Know what counts as breaking

A change is breaking if a client that works today could stop working. Removing or renaming a field. Making an optional field required. Tightening validation so previously accepted input is rejected. Changing a type, a status code, or the shape of an error. None of these can go into the current version.

A change is not breaking if it only adds: a new optional field in the response, a new endpoint, a new optional parameter. Clients that ignore the new thing keep working. Most changes are this kind, and they do not need a new version.

Prefer expand and contract over a version bump

When you need to change a field, do it in three steps within the same version. Add the new field alongside the old one. Give consumers time to move, with the old field marked as deprecated in the docs and, if you can, in a response header. Then remove the old field. Most “breaking” changes can be done this way without ever cutting a new version.

When you do cut a new version

Keep the old one running. Route /v1 and /v2 to different handlers, share the code underneath where it still makes sense. Announce the end of life for the old version with a real date, tell the clients you know about directly, and watch your logs to see who is still calling it. Turn it off only when the traffic has actually moved, not when the date arrives.

Document the current shape, not the history

Consumers need to know what the API does now. A changelog is useful, but the reference should describe the present version clearly, with every field, every status code and an example. Half the support load on an API is people guessing because the docs were vague.

The short version

One version scheme, added early, in the URL. Add-only changes need no bump. Real changes use expand and contract. New versions are rare, and the old one lives until its callers have left.

Common questions

URL version or header version?

A version in the URL path is the most practical: easy to see, easy to route, easy to test in a browser. Header versioning is cleaner in theory and more awkward in daily use.

When is a change breaking?

If an existing well-behaved client could stop working: a removed field, a renamed field, a stricter validation, a changed type or status code. Adding an optional field is not breaking.

How long do we support an old version?

Long enough for the clients you know about to move, with a clear end date communicated up front. For an internal API that might be weeks; for a public one, much longer.