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: DomainSecurity
  url: security/versioning-protocols-domain-security.yml
- 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: kin@apievangelist.com