Versioning for API Designs
API versioning is the set of rules for changing an API without breaking existing clients. It covers what counts as a breaking change, how versions are expressed in URLs or headers, and how deprecations are announced with sunset dates. The goal is to let providers evolve while consumers migrate on their own schedule.
Stage: Lifecycle · Part of the API Design roadmap · Last reviewed 19 November 2026
What to learn in Versioning
- Classify a change as breaking or backward compatible with concrete examples
- Compare URL, header and media-type versioning and state their trade-offs
- Add new optional fields without breaking tolerant-reader clients
- Announce a deprecation using Deprecation and Sunset headers and a changelog
- Plan a migration window and monitor which clients still use old versions
Versioning interview questions
Which API changes are considered breaking?
Removing or renaming a field, changing a field's type or meaning, making an optional parameter required, tightening validation, removing an endpoint, or changing error codes clients rely on. Adding new optional fields or endpoints is usually safe if clients ignore unknown fields.
Should you put the API version in the URL or in a header?
A URL version like /v2/orders is visible, easy to route and simple to test in a browser, so it is the common choice. Header or media-type versioning keeps URLs stable and is purer REST, but it is harder to discover and cache. Pick one and apply it consistently.
Where Versioning fits in the API Design roadmap
Versioning belongs to the Lifecycle stage (intermediate level). Evolve safely.
Other units in this stage
Back to the full API Design roadmap