Versioning Without Breaking Everyone

Every API eventually needs to change in a way that would break existing clients - and unlike an internal codebase, you cannot simply update every caller at the same time you ship the change. Versioning is how an API makes breaking changes without breaking everyone who depends on it today.

• -Breaking: removing a field, renaming a field, changing a field's type or meaning, removing an endpoint, changing required request parameters.
• -Non-breaking (safe to ship without a version bump): adding a new optional field to a response, adding a new endpoint, adding a new optional query parameter.

The practical implication: most API evolution should be additive and non-breaking, reserving an actual version bump for the genuinely rare case where a breaking change is unavoidable - not treating every change as an excuse to cut a new version.

URL-path versioning (`/v1/...`, `/v2/...`) is explicit, cacheable, and trivially visible in logs and browser history - its downside is that it puts the version at the resource-identity level, which purists argue is philosophically odd (is `/v1/orders/42` really a different resource than `/v2/orders/42`?), but this objection rarely matters in practice, and URL-path versioning is by far the most common real-world convention for exactly the simplicity and visibility reasons above.

Header-based versioning keeps the URL itself stable across versions (arguably more "correct" REST, since the resource identity never changes), at the cost of being less visible - you can't tell which version a request is targeting just by looking at a URL in a browser or a log line. Either approach is defensible; the interview signal is picking one deliberately and being able to justify the trade-off, not treating the choice as arbitrary.

A `Deprecation` header (announcing this version is on its way out), a `Sunset` header (the actual date it stops working), and a `Link` header pointing at the replacement give clients real time and a clear migration path - versus silently removing the old version on a deploy, which turns a planned migration into an unplanned incident for anyone who hadn't moved yet.