Backend & Node.js · APIs, data and failure
How do you version an API and avoid breaking clients?
Short answer
Prefer additive, backward-compatible changes and version only when a breaking change is unavoidable. Common strategies are a path prefix, a version header or media type, each with different caching and routing trade-offs.
Versioning is a last resort, not a feature. Adding an optional field, a new endpoint or a new enum value that clients tolerate is usually safe. Removing a field, changing a type, changing semantics or making an optional input required is breaking.
Strategies
- Path versioning, such as /v1/users, is visible, easy to route and easy to cache
- A custom header or media type keeps URLs clean but is harder to test and share
- Query parameter versioning is simple but easy to omit accidentally
- Version the representation contract, not every deployment
- Run old and new versions in parallel during a deprecation window
GET /v1/users/42 HTTP/1.1
Host: api.example.com
GET /users/42 HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.v2+jsonA deprecation plan matters more than the mechanism. Announce the change, instrument usage per client, return a Deprecation or Sunset header, provide a migration guide and set a removal date. Monitor old-version traffic so you do not delete an endpoint that a forgotten internal client still calls.
Follow-ups you should expect
Interviewers use these to check whether the first answer was understanding or memorisation.
- 1Which changes are backward compatible?
- 2What are the trade-offs of path versus header versioning?
- 3How do you deprecate an endpoint safely?
- 4Does GraphQL remove the need for versioning?
Say it in the interview
I try to avoid versioning by making additive changes and keeping response shapes tolerant. When a breaking change is unavoidable, I usually use a path prefix because it is explicit in routing, logs and caches. I run the old and new versions in parallel, measure usage per client, announce a sunset date and give a migration path. The hard part is deprecation and client coordination, not the URL format.
Use this as a model, not a script. Saying it in your own words is what makes it survive follow-up pressure.
Related questions
Reading is step one
Now say it out loud.
Understanding an answer and delivering it under pressure are different skills. Rehearse this topic in a live Backend & Node.js mock interview and get scored feedback on depth, clarity and confidence.