topic
Verified 2026-09-18HTTP API Versioning and Deprecation
API versioning lets incompatible contract changes coexist while clients migrate deliberately.
Prefer additive evolution where possible. When a breaking version is necessary, document the selection mechanism, keep representations and error semantics consistent, emit Deprecation and Sunset signals, and publish a migration path before removal.
httpapiversioninglifecycle
Reference (http)
GET /api/v2/users HTTP/1.1 Deprecation: @1798761600 Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Prefer additive evolution where possible. When a breaking version is necessary, document the selection mechanism, keep representations and error semantics consistent, emit Deprecation and Sunset signals, and publish a migration path before removal.
Common mistakes
- Putting a version only in documentation, silently changing the meaning of an existing field, or sending a removal date without a supported replacement.
Related
Sources