Versioning an API is not optional once you have external clients. But which strategy to choose? URI, headers, query parameter? Here are the trade-offs of each approach.
API versioning is one of those technical decisions that seem trivial at first and can become a maintenance nightmare as the API grows. The fundamental rule: never introduce breaking changes without versioning. Removing a field, renaming a property, changing a type — all of this breaks existing clients without warning. Adding an optional field, on the other hand, is generally backward-compatible.
Three main strategies exist. URI versioning (/api/v1/users) is the most explicit and readable. Each version is a
distinct URL, easy to route, cache, document separately. It is the most widespread and what we recommend for most cases.
Header versioning (Accept: application/vnd.myapi.v2+json) is more REST-pure but less convenient to use and debug.
Query parameter versioning (?version=2) is simple but pollutes URLs and logs.
The real question is not how to version but when to deprecate. Once published, an API version creates debt. You need a clear policy: minimum support period, client communications, monitoring of old version usage to identify clients to migrate. The ideal is to avoid version proliferation by evolving the API additively as long as possible — and limiting breaking changes to genuine architectural needs.
- Prefer URI versioning for its simplicity
- Define your deprecation policy upfront
- Monitor usage of each version in production
- Communicate breaking changes well in advance