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

versioning.yaml 
- name: Versioning
  type: Versioning
  url: https://developers.example.com/versioning
  source_date: '2026-08-17'
  data:
    scheme: sequential
    location: path
    path_pattern: /v{version}
    current: '3'
    default: '2'
    required: true
    pinning: per-request
    supported:
      - version: '2'
        status: deprecated
        sunset: '2027-02-01'
      - version: '3'
        status: current

Standards

HTTP Headers

HeaderDirectionSpecDescription
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

OpenAPI Expression

Link Relations

Governance Rules

Risk & Compliance

Compliance:

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

Suggested Metrics

Example Implementations

Related Properties

Tags


All Common Properties