Summary
API versioning manages change without breaking clients. Common strategies include URI versions, headers, media types, and backward-compatible evolution.
Interview Points
- Prefer backward-compatible additive changes when possible.
- URI versioning is simple and visible.
- Header or media-type versioning keeps URLs cleaner but is less obvious.
- Breaking changes need migration windows and deprecation policy.
- Version contracts, not just code.
2-3 Minute Interview Script
“API versioning is about changing an API without breaking existing clients. The best versioning strategy is often to avoid breaking changes by making additive changes: new optional fields, new endpoints, or tolerant readers.
When breaking changes are necessary, URI versioning like
/v1and/v2is simple and discoverable. Header or media-type versioning can be cleaner, but it is harder for humans and tooling to see.The senior part is lifecycle management: documentation, client migration, deprecation timelines, metrics on version usage, and clear ownership.
Interview answer: evolve compatibly by default; version only when semantics break; measure old version usage before shutting it down.”
Follow-Ups
- What counts as a breaking change?
- How do you deprecate an API safely?