How do you version a public API without breaking existing clients?
Put the version in the URL (/v1/) or a header, never change the meaning of existing fields, add new fields as optional, and announce deprecations with a long sunset period. Prefer additive changes so versions are rarely needed.
Explain it simply
Once an Android app is installed on a million phones, you cannot force every user to update. A breaking API change would crash those old apps, so versioning protects them.
Common approaches:
- URL versioning: /v1/users, /v2/users. Most visible and easiest to route and cache.
- Header versioning: Accept: application/vnd.myapi.v2+json. Cleaner URLs, harder to test in a browser.
- Query parameter: ?version=2. Simple but easy to forget.
What counts as breaking: removing or renaming a field, changing a type, changing meaning, making an optional field required. What is safe: adding a new optional field or a new endpoint.
Good practice:
- Prefer additive, backward-compatible changes and tolerate unknown fields on the client.
- Run old and new versions in parallel.
- Announce deprecation with dates, send a Deprecation or Sunset header, and watch usage before switching off.
Example
v1 response: {"name": "Asha Rao"}
Need first/last name?
Safe : v1 keeps "name", add optional "first_name","last_name".
Breaking: replace "name" with two fields -> create /v2.What to say in the interview
"I prefer additive, backward-compatible changes, and cut a new major version only for breaking ones. URL versioning is the simplest to operate. I run versions side by side, publish a deprecation timeline, and monitor traffic on the old version before retiring it."