HTTP 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

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.

Deprecation Sunset HTTP 410 Gone

Sources

MDN HTTP Reference