AP
API Versioning
API versioning strategies, backward compatibility, and deprecation lifecycle management
Details
Language / Topic
_UUniversal
Category
Architecture
Rules
balanced
- Version your API from the first release. Use URL path versioning (/v1/users) for simplicity or Accept header versioning for flexibility.
- Never remove or rename fields in an existing API version. Only add new optional fields — removal is always a breaking change.
- Deprecate before removing: announce deprecated endpoints at least one version in advance with Sunset and Deprecation headers.
- Document the supported versions and their end-of-life dates. Maintain at most two major versions simultaneously.
- Treat any change that could break an existing client as a major version bump: removing fields, changing types, renaming endpoints, altering error codes.
- Add new optional fields freely within a version — these are backward-compatible. Require new fields only in new major versions.
- Return a Deprecation header with a date and a Link header pointing to migration documentation when deprecated endpoints are called.
- Log usage of deprecated endpoints per API key. Notify consumers directly before sunset — do not rely on headers alone.
- Run backward-compatibility tests: replay requests from the previous version against the new version and assert identical response shapes.
- Support content negotiation (Accept header) for response format evolution within a version.