Versioning
The details of how an API is being versioned with information about how change is being communicated with consumers across multiple channels. Having a formal approach to versioning published and communicated helps lay the ground work for change, but also keeps API consumers aligned with what has changed.
Also known as: API Versioning, SemVer, CalVer
Example
Standards
- Community spec Semantic Versioning 2.0.0
- Community spec Calendar Versioning (CalVer)
- IETF RFC 9110 — HTTP Semantics (media-type parameters §8.3.2)
- IETF RFC 6838 — Media Type Specifications and Registration Procedures
- IETF (historic) RFC 7231 — HTTP/1.1 Semantics and Content (historic, content negotiation)
- IETF RFC 5829 — Link Relation Types for Simple Version Navigation
- OpenAPI Initiative OpenAPI Specification (info.version)
- AsyncAPI Initiative AsyncAPI Specification (info.version)
HTTP Headers
| Header | Direction | Spec | Description |
|---|---|---|---|
Accept |
request | RFC 9110 §12.5.1 | Used with versioned media types (e.g. application/vnd.example.v2+json) for content negotiation. |
Content-Type |
response | RFC 9110 §8.3 | Echoes the negotiated versioned media type. |
API-Version |
request / response | De facto | Custom header used by some providers (e.g. Microsoft Graph, Stripe) to select an API version. |
Media Types
application/vnd.— RFC 6838 — Vendor-tree media type with explicit version segment..v +json application/json; version=— RFC 9110 §8.3.2 — Parameterised media type carrying a version parameter.
OpenAPI Expression
-
info.version(OpenAPI 3.x) — Free-form version string for the API document; SemVer or CalVer recommended. -
servers[].url(OpenAPI 3.x) — URL-path versioning (e.g. /v1, /v2) is expressed in the server URL. -
components.parameters(OpenAPI 3.x) — Header or query parameters can carry an api-version selector.
Link Relations
latest-version— RFC 5829successor-version— RFC 5829predecessor-version— RFC 5829working-copy— RFC 5829working-copy-of— RFC 5829
Governance Rules
oas-info-version(Spectral built-in) — info.version must be present and non-empty.oas-semver(Spectral built-in) — info.version should follow SemVer.oas-path-not-include-query(Spectral built-in) — Discourages query-string versioning embedded in path templates.
Risk & Compliance
Compliance:
- SOC 2 CC8.1 — change-management with traceable versions
- ISO/IEC 27001 A.12.1.2 — change management
Security: Ambiguous versioning lets clients pin to vulnerable behaviour or silently roll forward into untested code paths. Explicit, negotiated versions plus a published compatibility policy reduce regression-driven security incidents.
Tools
- oasdiff — Breaking-change detector (Apache-2.0)
- openapi-diff (OpenAPI Tools) — Diff (Apache-2.0)
- optic — Change tracking (MIT)
- semver (npm) — Library (ISC)
- Spectral — Linter (Apache-2.0)
Suggested Metrics
active_versions— Count of versions currently receiving production traffic.version_adoption_share— Traffic share per version; informs deprecation timing.breaking_changes_per_release— Number of breaking changes detected by oasdiff between consecutive releases.time_in_version— Median time clients stay on a major version before upgrading.
Example Implementations
- GitHub — Media-type and X-GitHub-Api-Version header versioning (e.g. application/vnd.github.v3+json).
- Stripe — Date-based versions pinned per account, with Stripe-Version request header overrides.
- Microsoft Graph — URL-path versioning between v1.0 and beta.
- Twilio — Path-based versioning (/2010-04-01/) with CalVer-style identifiers.
Related Properties
Tags
- Change
- Versioning
- Semantic