Versioning Strategies
BookNook wants to split a book's author string into a list of authors, since many books have several. Thousands of installed phone apps still read author. Change it in place and they break tonight. Versioning is how an API grows without pulling the floor out from under the people already standing on it.
The rule
Add freely; never remove or rename without a new version.
First, sort every change into one of two kinds:
- Non-breaking (safe in the current version): adding a new endpoint, adding an optional request field, adding a new field to a response. Well-written clients ignore fields they do not know.
- Breaking (needs a new version): removing or renaming a field, changing a field's type or meaning, making an optional field required, changing a URL or status code that callers rely on.
When a break is truly needed, there are three common places to put the version:
GET /v2/books/42 URI path
GET /books/42?version=2 query parameter
GET /books/42 Accept: application/vnd.booknook.v2+json header / media type- URI path (
/v1,/v2): the most visible and easiest to test, route and cache. BookNook uses it. - Query parameter: easy to add, but easy to forget, and it muddles the "which thing" of the path.
- Header or media type: keeps URLs clean and fits content negotiation, but is invisible in a browser bar and easy to miss in logs.
Whichever you choose, run old and new side by side, and deprecate the old one politely: announce a date, send a Deprecation or Sunset header on old responses, and watch traffic until it falls away.
The shortcut
For each proposed change, ask: "Would a client written yesterday still work tomorrow?" Yes → ship it in the current version. No → find a non-breaking way, or plan a new version.
Would yesterday's clients still work?
If
authordisappears, apps reading it break. So the plain rename is breaking.
The trap is versioning too often. Every version is a copy you must run, test and secure. Additive change should carry you most of the way.
Drills
Answer fast — trust the rule.
Which change is safe without a new version?
Where does GET /v2/loans put the version?
What is a real drawback of header-based versioning?
A new version is released. What should happen to the old one?
Remember
- Add freely; never remove or rename without a new version.
- Shortcut: would a client written yesterday still work tomorrow?
- Trap: breaking changes in place, and creating versions when an additive change would do.