API Versioning

When to use

• The user is changing an API response or request and needs to know if it breaks existing clients and requires a new version.
• The user must choose how to version an HTTP API — URI path, custom header, or media-type versioning.
• The user needs to retire an old API version and communicate deprecation and a sunset date to clients.

When NOT to use

• Do not cut a new API version for a purely additive, backward-compatible change such as adding an optional field or a new endpoint.
• Do not add a versioning scheme when a single team deploys the API and its only client together and can change both at once.

Core guidance