Versioning Protocols

aid: versioning-protocols
name: Versioning Protocols
description: >-
  Standards and methodologies for managing changes and updates to APIs, software
  interfaces, and data formats while maintaining backward compatibility and clear
  communication of breaking changes. Covers Semantic Versioning (SemVer), Calendar
  Versioning (CalVer), URI path versioning, header-based versioning, and deprecation
  management strategies. Used by developers, platform teams, and API governance
  programs to build maintainable and predictable API lifecycle policies.
type: Index
url: https://raw.githubusercontent.com/api-evangelist/versioning-protocols/refs/heads/main/apis.yml
created: '2025'
modified: '2026-05-03'
specificationVersion: '0.19'
tags:
  - API Design
  - Backward Compatibility
  - Software Development
  - Version Control
  - Semantic Versioning
  - API Lifecycle
  - Deprecation
apis:
  - aid: versioning-protocols:semver
    name: Semantic Versioning (SemVer)
    description: >-
      Semantic Versioning is a versioning scheme using a MAJOR.MINOR.PATCH format
      where MAJOR increments denote breaking changes, MINOR increments indicate
      new backward-compatible features, and PATCH increments represent backward-compatible
      bug fixes. SemVer 2.0.0 is the canonical specification maintained at semver.org.
    humanURL: https://semver.org/
    tags:
      - Semantic Versioning
      - SemVer
      - Breaking Changes
      - API Versioning
    properties:
      - type: Documentation
        url: https://semver.org/
      - type: Specification
        url: https://semver.org/spec/v2.0.0.html
      - type: JSONSchema
        url: https://raw.githubusercontent.com/api-evangelist/versioning-protocols/refs/heads/main/json-schema/versioning-protocols-semver-schema.json
      - type: JSONStructure
        url: https://raw.githubusercontent.com/api-evangelist/versioning-protocols/refs/heads/main/json-structure/versioning-protocols-semver-structure.json

  - aid: versioning-protocols:calver
    name: Calendar Versioning (CalVer)
    description: >-
      Calendar Versioning (CalVer) uses the release date as the version identifier,
      typically in YYYY.MM.DD or YYYY-MM-DD format. Used by APIs like Stripe (date-based
      versions e.g., 2024-06-01) to communicate when an API version was released
      rather than the impact of changes.
    humanURL: https://calver.org/
    tags:
      - Calendar Versioning
      - CalVer
      - Date-Based Versioning
      - API Versioning
    properties:
      - type: Documentation
        url: https://calver.org/
      - type: JSONSchema
        url: https://raw.githubusercontent.com/api-evangelist/versioning-protocols/refs/heads/main/json-schema/versioning-protocols-calver-schema.json

  - aid: versioning-protocols:uri-path-versioning
    name: URI Path Versioning
    description: >-
      URI path versioning embeds the API version in the URL path, typically as the
      major version number (e.g., /v1/users, /v2/users). The most widely adopted
      strategy for public REST APIs due to its explicitness, cache-friendliness, and
      ease of documentation. Minor and patch changes are deployed in place under
      the same major version path.
    humanURL: https://www.askantech.com/api-versioning-strategies-rest-header-url-deprecation-guide/
    tags:
      - URI Versioning
      - Path Versioning
      - REST
      - API Design
    properties:
      - type: Documentation
        url: https://www.askantech.com/api-versioning-strategies-rest-header-url-deprecation-guide/
      - type: JSONSchema
        url: https://raw.githubusercontent.com/api-evangelist/versioning-protocols/refs/heads/main/json-schema/versioning-protocols-uri-path-versioning-schema.json

  - aid: versioning-protocols:header-versioning
    name: Header-Based Versioning
    description: >-
      Header-based versioning passes the API version in a custom HTTP request header
      (e.g., API-Version: 2026-04-01 or Accept: application/vnd.api.v2+json), keeping
      URLs clean and enabling more granular version control. Aligns well with full
      SemVer strings and content negotiation patterns.
    humanURL: https://redocly.com/blog/api-versioning-best-practices
    tags:
      - Header Versioning
      - Content Negotiation
      - REST
      - API Design
    properties:
      - type: Documentation
        url: https://redocly.com/blog/api-versioning-best-practices

  - aid: versioning-protocols:openapi-versioning
    name: OpenAPI Versioning
    description: >-
      OpenAPI handles versioning through the info.version field (using SemVer),
      the deprecated flag on individual operations, parameters, and schemas, and
      multiple server entries for different API versions. Tools like oasdiff enable
      automated breaking change detection between OpenAPI spec versions.
    humanURL: https://openapispec.com/docs/how/how-does-openapi-handle-api-versioning/
    tags:
      - OpenAPI
      - API Specification
      - Breaking Changes
      - Deprecation
    properties:
      - type: Documentation
        url: https://openapispec.com/docs/how/how-does-openapi-handle-api-versioning/

common:
  - type: Website
    url: https://semver.org/
  - type: Documentation
    url: https://semver.org/spec/v2.0.0.html
  - type: Vocabulary
    url: https://raw.githubusercontent.com/api-evangelist/versioning-protocols/refs/heads/main/vocabulary/versioning-protocols-vocabulary.yaml
  - type: Features
    data:
      - name: Semantic Versioning
        description: MAJOR.MINOR.PATCH versioning that communicates the impact of changes on API consumers.
      - name: Calendar Versioning
        description: Date-based versioning (YYYY.MM.DD) that communicates the freshness of an API release.
      - name: URI Path Versioning
        description: Embedding the API major version in the URL path for explicit, cache-friendly versioning.
      - name: Header-Based Versioning
        description: Passing the API version in HTTP headers for clean URL structures and content negotiation.
      - name: Query Parameter Versioning
        description: Appending the version to request URLs as a query string parameter (e.g., ?version=2).
      - name: Deprecation Management
        description: Structured policies for communicating and retiring old API versions with adequate notice.
      - name: Breaking Change Detection
        description: Tooling and processes to identify breaking changes between API versions using spec diffing.
      - name: N-2 Support Policy
        description: Support policy maintaining the current major version plus the two previous versions before retirement.
  - type: UseCases
    data:
      - name: API Lifecycle Governance
        description: Establish organizational versioning policies that balance innovation with backward compatibility.
      - name: Breaking Change Communication
        description: Communicate breaking changes clearly to API consumers with version bumps and deprecation notices.
      - name: Multi-Version Support
        description: Maintain multiple active API versions simultaneously to support consumers at different adoption stages.
      - name: Automated Change Detection
        description: Integrate spec diffing tools into CI/CD pipelines to detect breaking changes before release.
      - name: Deprecation Planning
        description: Plan and execute API version deprecations with 12-18 months notice and migration guides.
  - type: Integrations
    data:
      - name: Kong API Gateway
        description: Deploy version routing plugins, deprecation headers, and logging in Kong for API versioning.
      - name: Apigee
        description: Support versioned API proxies and detailed version analytics in Google Apigee.
      - name: AWS API Gateway
        description: Run different stages for version control and access management in AWS API Gateway.
      - name: Azure API Management
        description: First-class support for multiple API versions and revisions in Azure APIM.
      - name: oasdiff
        description: Open-source tool for detecting breaking changes between OpenAPI specification versions.
      - name: Redocly
        description: API documentation and governance platform with versioning and deprecation management features.
maintainers:
  - FN: Kin Lane
    email: [email protected]