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.