Versioning Without Breaking Everyone
You'll learn to
- -Tell a breaking change from a safe one, and run an old client against each
- -Compare version in the URL with version in a header, and defend a choice
- -Retire a version politely with the Deprecation and Sunset headers
Every API eventually needs a change that would break existing clients. Unlike an internal codebase, you cannot update every caller at the same moment you ship. Versioning is how an API makes a breaking change without breaking everyone who depends on it today.
An Analogy: Changing a Plug
A country decides to change its wall sockets. If every house were swapped overnight, every lamp would stop working. The kind approach is to keep the old socket for years, add the new one next to it, announce the end date early, and only then remove the old. A version number is how an API keeps the old socket working while the new one is introduced.
What Counts as Breaking
- -Breaking: removing a field, renaming a field, changing a field's type or meaning, removing an endpoint, making an optional request parameter required.
- -Safe, no version bump needed: adding an optional field to a response, adding a new endpoint, adding an optional query parameter.
The demo runs an old client against each kind of change. The client reads a field called user_name. An added field leaves it untouched. A rename removes what it reads.
So most evolution should be additive. Reserve a real version bump for the rare case where a breaking change is unavoidable, rather than treating every change as a reason for a new version.
URL-Path Versioning: Simple and Explicit
GET /v1/orders/42
GET /v2/orders/42Putting the version in the path (/v1/..., /v2/...) is explicit, cacheable, and easy to see in logs and a browser's history. Purists object that the same order should not live at two addresses, but that objection rarely matters in practice, and this is by far the most common real-world convention.
The Alternative: Header-Based Versioning
GET /orders/42
Accept: application/vnd.example.v2+jsonA request header keeps the URL stable across versions, which is arguably more faithful to REST, since a resource's identity never changes. The cost is visibility: you cannot tell which version a request wants from a URL in a browser or a log line. Either approach is defensible. The signal is choosing one on purpose and naming the trade-off.
Deprecating Without Surprising Anyone
GET /v1/orders/42
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Link: </v2/orders/42>; rel="successor-version"A Deprecation header announces that this version is on its way out, a Sunset header gives the date it stops working, and a Link header points to the replacement. That gives clients real time and a clear path, instead of silently removing a version in a deploy and turning a planned migration into an incident.
A version bump is no excuse to skip backward-compatible design. If "we will just bump to v3 next time" is the default answer to every breaking change, you end up maintaining many versions at once.
Interview Signal is part of Pro
See a real weak answer next to a real strong one for this exact topic.
Quiz is part of Pro
Test what you just read with a short quiz, and bank the XP.
Design Version Control in the API Design Lab's REST Foundations act.
Discussion0
Join the Discussion
Sign in to leave comments, reply to others, or like insights.
No comments yet. Be the first to start the thread!