API versioning strategies
Every successful API eventually needs to change. New fields appear, old ones become irrelevant, and occasionally a breaking change is unavoidable. Versioning is how you evolve an API without breaking the clients that depend on it. The strategy you choose affects developer experience, caching, tooling, and how painful future migrations will be.
Breaking vs non-breaking changes
Not every change requires a new version. Adding a new optional field or a new endpoint is backward compatible and safe. Removing a field, renaming it, changing its type, or altering behavior is a breaking change and is exactly what versioning exists to manage.
- Safe: adding new fields, new endpoints, new optional parameters.
- Breaking: removing or renaming fields, changing types, changing required parameters, altering response semantics.
URL path versioning
The most common and visible approach puts the version directly in the URL. It is explicit, easy to route, and trivial to test in a browser.
GET /v1/users/42
GET /v2/users/42The downside is that it technically violates the idea that a URL identifies a single resource, and it can lead to duplicated routing logic. In practice, its clarity makes it the default choice for many public APIs.
Query parameter versioning
Here the version is passed as a query parameter. It keeps the base URL stable but is easy to forget and can complicate caching.
GET /users/42?version=1
GET /users/42?version=2Header versioning
The version is sent in a custom header or via content negotiation with the Accept header. This keeps URLs clean and is considered the most RESTful approach, but it is less discoverable and harder to test casually.
GET /users/42
Accept: application/vnd.myapi.v2+jsonComparing the approaches
| Strategy | Visibility | Caching | Best for |
|---|---|---|---|
| URL path | High | Easy | Public APIs, clear major versions |
| Query parameter | Medium | Tricky | Quick toggles, internal use |
| Header / Accept | Low | Easy | Strict REST, clean URLs |
Best practices
- Version only when you must - favor additive, backward-compatible changes.
- Deprecate gracefully: announce, document, and give consumers time before removal.
- Communicate timelines and sunset dates clearly through headers and docs.
- Keep at most one or two active major versions to limit maintenance burden.
- Document every version and its differences so consumers can migrate confidently.
Conclusion
There is no single correct way to version an API, but there is a correct mindset: treat your API as a contract and change it responsibly. URL versioning is the pragmatic default for most public APIs, while header versioning suits teams that value clean, RESTful design. Whatever you choose, the real win comes from minimizing breaking changes and communicating clearly with the people who depend on you.