What are the different API versioning strategies?

intermediate Pro

The full answer covers the core mechanics, when this pattern wins, and the trade-offs interviewers most often probe. It includes a code sample. Read it once at your own pace, then try to recall the structure from memory before the interview. Pro also includes this question's interview lens - the likely follow-up probes and what you can say in the room.

Full answer + code samples + AI explanations

Unlock to read the complete answer for this premium question.

Browse free API Design questions → Unlock all · $10/mo

Guided practice for API Design One question at a time. Answer out loud, get graded, see what you missed.

Related concept

Versioning an API: changing the contract you already published

Only a breaking change needs a new version, and most changes are additive. The deprecation lifecycle matters far more than where the version number goes.

For this question · chapter 2 of 3

2/3 Is it breaking? That alone decides

Is it breaking? That alone decides

The first step is to sort six kinds of change into two trays, one for each possible answer. One tray is for changes that ship in place, in the version clients already use. The other tray is for changes that need a new version. So this sort decides whether v2 exists at all.
Old clients never asked for the new key, and they never read it. So nothing they run changes. The optional field ships in the current version, with no new version number. So far, one change has shipped this way. Additive changes are optional fields, new endpoints, and new inputs that the server can fill with a default value.
A new route is safe to add, because no client can already depend on its URL. So the new endpoint also ships in the current version. The list of changes that ship in place now holds 2 changes. Adding to what you offer is not the same as changing what you already offer.
Renaming a field is the first of the six changes that needs a new version. A rename looks like an edit. But it acts like a deletion, because every client that parses the old name stops finding that name the moment you ship.
A type change breaks clients, even when every value stays the same. Every client language parses the string "42" and the number 42 differently. A strict parser rejects a value of the wrong type outright. So this change needs a new version.
Making an optional field required is the change people get wrong. This change needs a new version. You added nothing to the response, but every client that has never sent the field now gets a 422 error. Tightening a rule breaks clients exactly like removing a field does.
A change in meaning is the breaking change that ships by accident. The total field now leaves out the tax that it used to include. Every schema test still passes, but every invoice that uses total is now wrong. So this change needs a new version too.
Four of the six changes break clients, so the API gets a v2. A version in the path shows up in every log and gives each version its own cache entries. A version in a header keeps URLs clean but needs a Vary header to stop the cache from serving v1 to a v2 client. Pick one of the four places for the version number and stop arguing.

Chapter 2 · step 1 of 8

The first step is to sort six kinds of change into two trays, one for each possible answer. One tray is for changes that ship in place, in the version clients already use. The other tray is for changes that need a new version. So this sort decides whether v2 exists at all.

1 of 8 Use ← → or swipe See the concept: all 3 chapters in it

Want a quick review of the fundamentals? See the API Design cheatsheet.

← Back to all API Design questions

Pro · $10/mo

74 of 92 API Design answers are in Pro.

Full answers, code samples, and AI explanations that go simpler or deeper. Cancel anytime.

Full answers + code
AI explanations, simpler or deeper
1,000 AI credits / month
Cancel anytime

Get Pro → See plans & pricing →