How do you handle backward compatibility in APIs?

expert 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 · chapters 1 and 2 of 3

1/3 The line holds until a field is renamed

The line holds until a field is renamed

A published response shape is code that other people already run in production, not documentation. You cannot redeploy that code for them. Each strand in the line stands for one field your API returns. The contract test checks those fields, and the test passes.
Adding an optional field such as email to the /v1 shape costs nothing. A tolerant reader ignores keys it does not recognise, so clients on /v1 skip the new email key. The contract test runs again and still passes. Additive changes like this one are most of the changes any API ever makes.
A new required input is still an additive change if the server can answer without it. Here the server fills in a default role for any client that does not send a role. The default keeps old clients working correctly. So the published contract still holds, now with a fourth additive change.
A rename is two changes: a removal and an addition. The removal is the part that breaks clients. The name field becomes full_name, so a client that reads u["name"] gets a KeyError. The contract test (the check against what that client expects) fails. So the rename has broken that client.
A new version exists to move a breaking change out of /v1. Here the rename moves to /v2, and /v1 goes back to the shape it published. So the old client works again, and the contract test passes. A new version is only for breaking changes, so a change that breaks nothing should never get one.

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 1 · step 1 of 5

A published response shape is code that other people already run in production, not documentation. You cannot redeploy that code for them. Each strand in the line stands for one field your API returns. The contract test checks those fields, and the test passes.

1 of 5 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 →