Skip to main content

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

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.

Back to the full API Design roadmap