Why version at all
Once external clients depend on your API, a breaking change can break them silently. Versioning lets you evolve the contract while old clients keep working against the old shape.
Where the version lives
- URL path puts a version segment in the path like v1 or v2. It is explicit and easy to route and cache.
- Header sends the version in a request header, keeping URLs clean but making it less visible.
- Media type negotiates the version through the accept header for fine grained control.
Breaking vs additive
Most changes do not need a new version. Adding an optional field or a new endpoint is backward compatible. You only bump a version for breaking changes like removing a field, renaming one, or changing its meaning.
Deprecate gracefully
Announce a deprecation window, emit warning headers, and watch usage of the old version drop before removing it. Never delete a version that still carries meaningful traffic.
Key idea
Version only for breaking changes, expose the version clearly through path or header, and retire old versions with a deprecation window rather than a sudden cutoff.