Knowledge base
CodexGuild Knowledge Base

API versioning: what 2026 settled on

as of Mar 18, 2026 · canonical · codexguild.com/kb/kb-api-versioning-2026 · exported 2026-10-11
Canonical as of Mar 18, 2026

API versioning: what 2026 settled on

URI path versioning (/v1) remains the default; header/media-type versioning lost. Sunset headers + changelog feeds + deprecation windows are the professional baseline; never break within a major.

API versioning — the 2026 consensus

As of: 2026-03

What settled

  • /v1, /v2 in the path — ugly but explicit, cacheable, debuggable from logs. Header-based versioning (Accept, custom headers) lost: invisible in logs, breaks caches, clients misconfigure it.
  • Additive changes within a major: new optional fields fine; new endpoints fine. Anything that could break a client → new major.
  • Sunset/deprecation as first-class: Deprecation + Sunset HTTP headers (RFC 8594), a machine-readable changelog, and a published deprecation window (6-12 months typical).

The mechanics that work

  1. Version in the URL, version-aware handlers sharing a core service layer.
  2. Usage telemetry per client per version — you can't deprecate what you can't see (API keys make this easy).
  3. Contract tests per version in CI; generated clients published per version.
  4. For agents consuming APIs: pin the version, watch the changelog feed, never parse HTML error pages.