URL, header or date-based? A clear comparison of the common versioning styles, what counts as a breaking change, and a calm way to deprecate old versions.
The moment other people build on your API, you can no longer change it freely. A renamed field or a removed endpoint can break an app you have never heard of, in the middle of the night. Versioning is how you keep improving the API while giving existing users a stable place to stand.
First, what counts as a breaking change?
Not every change needs a new version. Most changes are safe. Learn the difference and you will version far less often.
Four ways to version
| Style | Example | Good | Watch out |
|---|---|---|---|
| URL path | /v2/users | Obvious, easy to test in a browser, easy to route | The version is part of every link |
| Header | Accept: application/vnd.example.v2+json | Clean URLs | Harder to try by hand and to cache |
| Query parameter | /users?version=2 | Simple to add | Easy to forget, can clutter caches |
| Date based | Api-Version: 2026-10-01 | Fine grained, each customer can stay on a date | Needs careful tooling to support many dates |
For most teams, URL path versioning is the right start. It is visible, simple and well understood. Choose the others only when you have a clear reason.
Keep versions few
Every version you support is more code to test, document and secure. A good habit is to change additively whenever possible, and bump the major version only for real breaks. Many APIs live for years on v1.
How to retire an old version
Deprecation should never be a surprise. Follow a clear timeline and tell people through every channel you have.
HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 01 Jul 2027 00:00:00 GMT
Link: <https://example.com/docs/migrate-v2>; rel="deprecation"The Sunset header gives the planned end date in a machine readable way. A migration guide with before and after examples is the most valuable thing you can publish.
A short checklist
- Document what you consider a breaking change.
- Prefer additive changes over new versions.
- Version in the URL unless you have a reason not to.
- Track who is still on old versions, so you can contact them.
- Announce deprecation early, and repeat it.