API versioning strategies — URL vs header vs content negotiation

API needs to evolve without breaking existing clients. Adding fields is safe but removing or changing fields breaks clients. Need a strategy for managing breaking changes.

(1) URL versioning (/v1/users, /v2/users): most common, easiest to understand, works with caching proxies. Downside: URL changes break bookmarks and require routing updates. (2) Header versioning (Accept: application/vnd.api+json;version=2): cleaner URLs, same URL serves different representations. (3) Non-breaking changes (safe without versioning): adding fields, adding optional parameters, adding new endpoints. (4) Breaking changes (require version): removing/renaming fields, changing types, changing semantics. (5) Additive-only approach: never remove, only add. Deprecate with headers (Deprecation, Sunset). (6) Support at most 2-3 versions simultaneously. (7) Use API evolution (field-level versioning) over endpoint versioning when possible.

Breaking changes in APIs cascade to all clients. Unlike a web app where you control the deployment, API clients update on their own schedule. Old versions must keep working.