evolution
API Versioning
Evolve the API without breaking existing clients by versioning the contract.
An API is a contract, and once external clients depend on it you cannot freely change its shape — removing a field or renaming an endpoint breaks every consumer that relied on the old form, and you rarely control when (or whether) they update. Versioning is how you evolve the contract while keeping existing clients working: you introduce a new version for incompatible changes and let consumers migrate on their own schedule.
A software product's "v2" — old binaries still work; new install gets the new behavior.
Key Concepts
1
There are a few established places to put the version. URL path versioning (/v1/orders, /v2/orders) is the most common and the most visible — easy to route, easy to test in a browser, and unambiguous, at the cost of arguably violating the idea that a URL identifies a single resource. Header or media-type versioning (Accept: application/vnd.company.v2+json) keeps URLs clean and is more "RESTful" in spirit, but is less discoverable and harder to try by hand. Query-parameter versioning (?version=2) is simple but awkward to manage. Whichever you pick, the key discipline is reserving a new version for genuinely breaking changes — removing or renaming fields, changing types, altering semantics — while making non-breaking additions in place.
/v1/orders/v2/ordersAccept: application/vnd.company.v2+json?version=2
2
The mature position interviewers look for is that versioning is a last resort, not a first reflex. Most evolution can and should be done backward-compatibly within a single version by adding optional fields and new endpoints rather than changing existing ones, so you avoid the substantial cost of maintaining multiple versions in parallel. When a breaking change is truly unavoidable, bump the version, run old and new side by side for a defined window, and pair it with a clear deprecation timeline so clients know when the old version will be retired. Path versioning is the pragmatic default for public APIs because its visibility makes that lifecycle easy to communicate.
3
What the interviewer is probing.
What the interviewer is probing.
4
1. "What are the versioning options?" *Probing:* breadth. *Stalls:* "In the URL." *Moves up:*
URI path, a custom header, content negotiation on the Accept header, or a query parameter.
1. "What are the versioning options?"
5
2. "Which would you choose?" *Probing:* the judgement. *Stalls:* "The header." *Moves up:* URI
versioning for public APIs — it is visible, cacheable and trivially testable in a browser, which
outweighs its theoretical impurity.
2. "Which would you choose?"
6
3. "When does a change require a new version?" *Probing:* the rule. *Stalls:* "Any change."
*Moves up:* only a breaking one — removing or renaming a field, changing a type, or tightening
validation. Additions do not.
3. "When does a change require a new version?"
7
4. "How many versions should you run?" *Probing:* the operational angle. *Stalls:* "All of
them." *Moves up:* as few as possible with a published deprecation timeline — every live version is
a maintenance and testing cost.
4. "How many versions should you run?"