Versioning

An index and topic collection covering API versioning patterns, schema evolution, and breaking-change detection across the API lifecycle. API versioning communicates change to consumers, while schema versioning and diff tooling makes those changes explicit, reviewable, and reversible. This collection brings together versioning approaches like SemVer and CalVer, registry-driven schema evolution platforms (Apollo, Buf, Apicurio, Confluent Schema Registry), spec-diff tools (oasdiff, Optic, Bump.sh, GraphQL Inspector), API documentation versioning (Stoplight, Scalar, Bump.sh), versioning headers and sunsetting practices (Stripe API Versioning, Sunset Header), and dependency-versioning automation (Dependabot, Renovate, Conventional Commits).

Versioning is profiled on the APIs.io network. Tagged areas include API Versioning, SemVer, CalVer, Schema Evolution, and Breaking Change.

The Versioning catalog on APIs.io includes 1 JSON-LD context.

Versioning’s developer surface includes developer portal and 1 more developer resources.

🌐 Visit website 📡 Profile data on GitHub

9.6/100 minimal ▬ flat Agent 0/100 human only Full breakdown ↓
scored 2026-10-23 · rubric v0.25.0 · Show this score on your site →

0 APIs 8 Features 8 Use Cases

API VersioningSemVerCalVerSchema EvolutionBreaking ChangeDeprecation Schema RegistrySpec DiffConventional CommitsSunset Header

Kin Score

Kin Score How this is scored →
scored 2026-10-23 · rubric v0.25.0

Composite quality — 9.6/100 · minimal

Contract Quality 3.1 / 21

Developer Ergonomics 1.6 / 17

Access Clarity 0.0 / 17

Operational Transparency 0.6 / 11

Contract Governance 0.0 / 10

Discoverability 4.1 / 9

Regulatory Posture 0.7 / 15

Agent readiness — 0/100 · human only

Machine-Readable Contract 0 / 18

Agentic Access Contract 0 / 10

Documented Reversibility 0 / 6

MCP Server 0 / 12

Machine-Readable Auth 0 / 10

Idempotency 0 / 9

Stable Error Semantics 0 / 8

Request/Response Examples 0 / 7

Rate-Limit Signaling 0 / 7

Typed Event Surface 0 / 6

Agent Skills 0 / 5

Well-Known Catalog 0 / 4

Consent & Bot Identity 0 / 3

A2A Agent Card 0 / 8

Dry-Run / Simulate Mode 0 / 4

Delegated User Identity 0 / 6

Protected Resource Metadata 0 / 5

Registration Without a Human 0 / 6

Agentic Commerce Well-Known Document 0 / 5

Pagination 5 / 5

Distinct Operations 3 / 3

Regulatory Posture applies to this provider. Its tags matched the Horizontal (data, software, accessibility, platform) regime, so Regulatory Posture carries 15 points of the composite. If this regime is wrong for your business, say so on your provider repo — the applicability map is public and we will correct it.

Create-or-Update Ergonomics could not be measured. We hold no machine-readable contract for this provider to read, so there is nothing to measure a write surface against. Excluded rather than scored zero: never-measured and measured-empty are different facts. Publishing an OpenAPI is what makes this facet — and several others — scorable at all.

The six quality facets above are damped to 85 points between them, because the conditional facet above carries the other 15. That is why each facet's contribution is shown against a damped maximum: raising a quality facet moves the composite by 85% of its nominal weight, not 100%. The full arithmetic is at apis.io/rating/.

Show this score on your site.

It updates itself when the score changes. Paste this where you link to your API docs:

<a href="https://apis.io/providers/versioning/"><img src="https://apis.io/badge/versioning/card.svg" alt="Versioning on APIs.io — Kin Score by API Evangelist"></a>

Other styles, a README pill and a shields.io endpoint are on the badge page.

Improve this rating by publishing the missing artifacts — every area above can be raised, and the full rubric is at apis.io/rating/. Every facet and dimension name above is a link: it opens that measurement's own page — what it means, the exact checks that feed it, how the whole catalog distributes on it, and the providers at the top of it. This rating is computed from github.com/api-evangelist/versioning: open an issue to ask a question, or submit a pull request to add artifacts. Submit an artifact on GitHub — free → Manage your own listing — the Influence plan, $499/mo →

Markets this provider is in provisional

The Kin Score Market layer reads a provider inside its market: its position, and how deep its integrations go. Depth is only comparable within a position. Provisional and unweighted: not part of the Kin Score or agent readiness.

Market	Position	Depth	Registered MCP server	Declares compatibility
Buf Schema Registry (public Protocol Buffers modules, gRPC / ConnectRPC schema publishers)	undeclared	-	-	-

Registered MCP server and declares compatibility are report only — not weighted. Undeclared means we found nothing we can read, so there is no number: we never infer integrations.

Features 8

Notable capabilities this provider offers.

Semantic and Calendar Versioning

Established conventions like SemVer (MAJOR.MINOR.PATCH) and CalVer (YYYY.MM) give API and library producers a shared vocabulary for communicating compatibility and release caden...

Breaking Change Detection

Spec-diff tools like oasdiff, openapi-diff, Optic, and GraphQL Inspector compare two versions of an API specification and classify changes as breaking, non-breaking, or unclassi...

Schema Registries and Evolution

Platforms like Apicurio, Confluent Schema Registry, Buf Schema Registry, and Apollo GraphOS track every version of a schema, enforce compatibility rules (backward, forward, full...

API Version Headers and Date-Based Versioning

Providers like Stripe and GitHub pin requests to a version via a header or date string, allowing the platform to ship new API behavior without breaking existing integrations.

Deprecation and Sunsetting

The Deprecation and Sunset HTTP headers (RFC 8594 / RFC 9745) and platform-level deprecation policies give consumers structured advance notice that an endpoint or version is goi...

Documentation and Changelog Versioning

Tools like Bump.sh, Stoplight, Scalar, LaunchNotes, and Keep a Changelog publish per-version API references and human-readable release notes alongside the underlying spec or cod...

Conventional Commits and Release Automation

The Conventional Commits specification encodes change type (feat, fix, BREAKING CHANGE) directly in commit messages so that SemVer bumps and changelogs can be generated automati...

Dependency Version Management

Bots like Dependabot and Renovate continuously open pull requests to upgrade dependencies, respecting SemVer ranges and surfacing breaking changes upstream.

Scroll for all 8

Semantic Vocabularies 1

JSON-LD contexts and semantic vocabularies used across these APIs.

Versioning Context

7 classes · 21 properties

JSON-LD

JSON Schema 2

Standalone JSON Schema definitions for this provider's data models.

APIVersion

12 properties

JSON SCHEMA

BreakingChange

11 properties

JSON SCHEMA

JSON Structure 2

JSON Structure definitions describing this provider's data shapes.

Versioning Api Version Structure

12 properties

JSON STRUCTURE

Versioning Breaking Change Structure

11 properties

JSON STRUCTURE

Examples 2

Example request and response payloads for these APIs.

Versioning Api Version Example

12 fields

EXAMPLE

Versioning Breaking Change Example

11 fields

EXAMPLE

Use Cases 8

What developers build with this provider.

Pre-Merge Breaking Change Gate

Run oasdiff or Optic in CI on every pull request that touches the OpenAPI spec and block the merge if breaking changes are introduced without an explicit major version bump.

Date-Pinned API Versions

Issue per-account or per-request API versions (e.g. Stripe's 2024-04-10 versioning) so customer integrations remain stable while the platform iterates rapidly behind the scenes.

Schema Registry Compatibility Enforcement

Producers and consumers of Kafka, gRPC, or GraphQL schemas register every revision in Apicurio, Confluent, Buf, or Apollo and the registry refuses incompatible changes at publis...

Multi-Version API Documentation

Publish v1, v2, and v3 documentation simultaneously through Bump.sh, Stoplight, or Scalar so consumers on older versions still have authoritative reference material.

Deprecation and Sunset Notification

Emit Deprecation and Sunset HTTP headers from deprecated endpoints, then track consumer migration through analytics before fully removing the version.

Automated SemVer Release

Use Conventional Commits plus tools like semantic-release to compute the next SemVer version, generate a changelog, tag the repo, and publish a release entirely from commit hist...

Continuous Dependency Upgrades

Configure Dependabot or Renovate to open weekly PRs for dependency upgrades, with SemVer-aware grouping and automatic merge for non-breaking patches.

API Changelog and Release Notes

Publish a structured changelog through LaunchNotes, Beamer, or Keep a Changelog conventions so consumers can review what changed in every API release.

Scroll for all 8

Integrations 10

Pre-built integrations with other platforms and tools.

Oasdiff

Open-source CLI and library that compares two OpenAPI specifications and classifies every change as breaking or non-breaking, with rule-level configuration.

Optic

API change-management platform that captures real traffic, generates OpenAPI, and gates pull requests on breaking changes against the existing spec.

Bump.sh

API documentation and changelog platform that publishes per-version OpenAPI and AsyncAPI references and surfaces diffs between releases.

Buf

Buf Schema Registry and CLI for Protocol Buffers, with first-class breaking-change detection and lint rules across proto versions.

Apollo GraphQL

Apollo GraphOS schema registry and Apollo Studio check every proposed GraphQL schema change against operations from real clients before publication.

Apicurio

Open-source schema registry from Red Hat for Avro, JSON Schema, OpenAPI, AsyncAPI, and Protobuf, with pluggable compatibility rules.

Stripe

Stripe's date-based API versioning model pins every integration to a release date and provides a Versioning Stripe API reference for upgrading between versions.

Dependabot

GitHub-native dependency-update automation that opens PRs for upgrades, respecting SemVer ranges and security advisories.

Renovate

Configurable dependency upgrade bot with SemVer-aware grouping, scheduling, and automerge across npm, Maven, Docker, and many other ecosystems.

Sunset Header

Standard HTTP response header (RFC 8594) for communicating the date at which a resource will become unavailable, used together with Deprecation (RFC 9745).

Scroll for all 10

Resources

Get Started 1

Portal, sign-up, and the first successful call

Portal

Portal

Build 1

SDKs, sample code, and the tooling you integrate with

GitHubOrganization

GitHubOrganization

Source (apis.yml)

aid: versioning
name: Versioning
description: An index and topic collection covering API versioning patterns, schema evolution, and breaking-change detection
  across the API lifecycle. API versioning communicates change to consumers, while schema versioning and diff tooling makes
  those changes explicit, reviewable, and reversible. This collection brings together versioning approaches like SemVer and
  CalVer, registry-driven schema evolution platforms (Apollo, Buf, Apicurio, Confluent Schema Registry), spec-diff tools (oasdiff,
  Optic, Bump.sh, GraphQL Inspector), API documentation versioning (Stoplight, Scalar, Bump.sh), versioning headers and sunsetting
  practices (Stripe API Versioning, Sunset Header), and dependency-versioning automation (Dependabot, Renovate, Conventional
  Commits).
type: Index
image: https://kinlane-images.s3.amazonaws.com/shared/apis-json/apis-json-logo.jpg
tags:
- API Versioning
- SemVer
- CalVer
- Schema Evolution
- Breaking Change
- Deprecation
- Schema Registry
- Spec Diff
- Conventional Commits
- Sunset Header
url: https://raw.githubusercontent.com/api-evangelist/versioning/refs/heads/main/apis.yml
created: '2026-05-19'
modified: '2026-05-19'
specificationVersion: '0.19'
apis: []
network:
- name: Apicurio
  url: https://raw.githubusercontent.com/api-evangelist/apicurio/refs/heads/main/apis.yml
- name: Apollo GraphQL
  url: https://raw.githubusercontent.com/api-evangelist/apollo-graphql/refs/heads/main/apis.yml
- name: Axway
  url: https://raw.githubusercontent.com/api-evangelist/axway/refs/heads/main/apis.yml
- name: Beamer
  url: https://raw.githubusercontent.com/api-evangelist/beamer/refs/heads/main/apis.yml
- name: Buf
  url: https://raw.githubusercontent.com/api-evangelist/buf/refs/heads/main/apis.yml
- name: Bump.sh
  url: https://raw.githubusercontent.com/api-evangelist/bump-sh/refs/heads/main/apis.yml
- name: Changelog
  url: https://raw.githubusercontent.com/api-evangelist/changelog/refs/heads/main/apis.yml
- name: CHANGELOG.md (Keep a Changelog)
  url: https://raw.githubusercontent.com/api-evangelist/changelog-md/refs/heads/main/apis.yml
- name: Confluent
  url: https://raw.githubusercontent.com/api-evangelist/confluent-the-data-streaming-platform/refs/heads/main/apis.yml
- name: Dapr
  url: https://raw.githubusercontent.com/api-evangelist/dapr/refs/heads/main/apis.yml
- name: Dependabot.yml
  url: https://raw.githubusercontent.com/api-evangelist/dependabot-yml/refs/heads/main/apis.yml
- name: GitHub
  url: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/apis.yml
- name: GitLab
  url: https://raw.githubusercontent.com/api-evangelist/gitlab/refs/heads/main/apis.yml
- name: LaunchNotes
  url: https://raw.githubusercontent.com/api-evangelist/launchnotes/refs/heads/main/apis.yml
- name: Liblab
  url: https://raw.githubusercontent.com/api-evangelist/liblab/refs/heads/main/apis.yml
- name: Oasdiff
  url: https://raw.githubusercontent.com/api-evangelist/oasdiff/refs/heads/main/apis.yml
- name: Optic
  url: https://raw.githubusercontent.com/api-evangelist/optic/refs/heads/main/apis.yml
- name: Redpanda
  url: https://raw.githubusercontent.com/api-evangelist/redpanda/refs/heads/main/apis.yml
- name: Renovate
  url: https://raw.githubusercontent.com/api-evangelist/renovate-json/refs/heads/main/apis.yml
- name: Scalar
  url: https://raw.githubusercontent.com/api-evangelist/scalar/refs/heads/main/apis.yml
- name: Schema Evolution
  url: https://raw.githubusercontent.com/api-evangelist/schema-evolution/refs/heads/main/apis.yml
- name: Sentry
  url: https://raw.githubusercontent.com/api-evangelist/sentry/refs/heads/main/apis.yml
- name: Spectral
  url: https://raw.githubusercontent.com/api-evangelist/spectral/refs/heads/main/apis.yml
- name: Stoplight
  url: https://raw.githubusercontent.com/api-evangelist/stoplight/refs/heads/main/apis.yml
- name: Stripe
  url: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/apis.yml
- name: Sunset Header
  url: https://raw.githubusercontent.com/api-evangelist/sunset-header/refs/heads/main/apis.yml
- name: Versioning Protocols
  url: https://raw.githubusercontent.com/api-evangelist/versioning-protocols/refs/heads/main/apis.yml
common:
- type: Portal
  url: https://apievangelist.com
- type: GitHubOrganization
  url: https://github.com/api-evangelist
- type: Features
  data:
  - name: Semantic and Calendar Versioning
    description: Established conventions like SemVer (MAJOR.MINOR.PATCH) and CalVer (YYYY.MM) give API and library producers
      a shared vocabulary for communicating compatibility and release cadence to consumers.
  - name: Breaking Change Detection
    description: Spec-diff tools like oasdiff, openapi-diff, Optic, and GraphQL Inspector compare two versions of an API specification
      and classify changes as breaking, non-breaking, or unclassified before they ship to production.
  - name: Schema Registries and Evolution
    description: Platforms like Apicurio, Confluent Schema Registry, Buf Schema Registry, and Apollo GraphOS track every version
      of a schema, enforce compatibility rules (backward, forward, full), and prevent incompatible deploys.
  - name: API Version Headers and Date-Based Versioning
    description: Providers like Stripe and GitHub pin requests to a version via a header or date string, allowing the platform
      to ship new API behavior without breaking existing integrations.
  - name: Deprecation and Sunsetting
    description: The Deprecation and Sunset HTTP headers (RFC 8594 / RFC 9745) and platform-level deprecation policies give
      consumers structured advance notice that an endpoint or version is going away.
  - name: Documentation and Changelog Versioning
    description: Tools like Bump.sh, Stoplight, Scalar, LaunchNotes, and Keep a Changelog publish per-version API references
      and human-readable release notes alongside the underlying spec or code change.
  - name: Conventional Commits and Release Automation
    description: The Conventional Commits specification encodes change type (feat, fix, BREAKING CHANGE) directly in commit
      messages so that SemVer bumps and changelogs can be generated automatically.
  - name: Dependency Version Management
    description: Bots like Dependabot and Renovate continuously open pull requests to upgrade dependencies, respecting SemVer
      ranges and surfacing breaking changes upstream.
- type: UseCases
  data:
  - name: Pre-Merge Breaking Change Gate
    description: Run oasdiff or Optic in CI on every pull request that touches the OpenAPI spec and block the merge if breaking
      changes are introduced without an explicit major version bump.
  - name: Date-Pinned API Versions
    description: Issue per-account or per-request API versions (e.g. Stripe's 2024-04-10 versioning) so customer integrations
      remain stable while the platform iterates rapidly behind the scenes.
  - name: Schema Registry Compatibility Enforcement
    description: Producers and consumers of Kafka, gRPC, or GraphQL schemas register every revision in Apicurio, Confluent,
      Buf, or Apollo and the registry refuses incompatible changes at publish time.
  - name: Multi-Version API Documentation
    description: Publish v1, v2, and v3 documentation simultaneously through Bump.sh, Stoplight, or Scalar so consumers on
      older versions still have authoritative reference material.
  - name: Deprecation and Sunset Notification
    description: Emit Deprecation and Sunset HTTP headers from deprecated endpoints, then track consumer migration through
      analytics before fully removing the version.
  - name: Automated SemVer Release
    description: Use Conventional Commits plus tools like semantic-release to compute the next SemVer version, generate a
      changelog, tag the repo, and publish a release entirely from commit history.
  - name: Continuous Dependency Upgrades
    description: Configure Dependabot or Renovate to open weekly PRs for dependency upgrades, with SemVer-aware grouping and
      automatic merge for non-breaking patches.
  - name: API Changelog and Release Notes
    description: Publish a structured changelog through LaunchNotes, Beamer, or Keep a Changelog conventions so consumers
      can review what changed in every API release.
- type: Integrations
  data:
  - name: Oasdiff
    description: Open-source CLI and library that compares two OpenAPI specifications and classifies every change as breaking
      or non-breaking, with rule-level configuration.
  - name: Optic
    description: API change-management platform that captures real traffic, generates OpenAPI, and gates pull requests on
      breaking changes against the existing spec.
  - name: Bump.sh
    description: API documentation and changelog platform that publishes per-version OpenAPI and AsyncAPI references and surfaces
      diffs between releases.
  - name: Buf
    description: Buf Schema Registry and CLI for Protocol Buffers, with first-class breaking-change detection and lint rules
      across proto versions.
  - name: Apollo GraphQL
    description: Apollo GraphOS schema registry and Apollo Studio check every proposed GraphQL schema change against operations
      from real clients before publication.
  - name: Apicurio
    description: Open-source schema registry from Red Hat for Avro, JSON Schema, OpenAPI, AsyncAPI, and Protobuf, with pluggable
      compatibility rules.
  - name: Stripe
    description: Stripe's date-based API versioning model pins every integration to a release date and provides a Versioning
      Stripe API reference for upgrading between versions.
  - name: Dependabot
    description: GitHub-native dependency-update automation that opens PRs for upgrades, respecting SemVer ranges and security
      advisories.
  - name: Renovate
    description: Configurable dependency upgrade bot with SemVer-aware grouping, scheduling, and automerge across npm, Maven,
      Docker, and many other ecosystems.
  - name: Sunset Header
    description: Standard HTTP response header (RFC 8594) for communicating the date at which a resource will become unavailable,
      used together with Deprecation (RFC 9745).
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com
humanURL: https://apievangelist.com

Work with this as data

Every provider here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for providers

9 MCP tools reach this

find_providersBrowse and filter every provider in the catalog.
get_provider_artifactsEvery artifact this provider publishes, grouped by type.
get_provider_operationsEvery operation across all of their OpenAPIs — one call instead of parsing every spec.
get_provider_toolsEvery MCP tool they ship, with the operation each wraps.
get_provider_evidenceHow each part of their score was established. Free — the basis for a claim should not sit behind it.
get_provider_ratingPRO — composite, band, trend and facet scores.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This provider

curl "https://apis.io/api/v1/providers/versioning"

All providers

curl "https://apis.io/api/v1/providers?limit=25"

Every operation they expose

curl "https://apis.io/api/v1/providers/versioning/operations?limit=25"

How their score was established

curl "https://apis.io/api/v1/providers/versioning/evidence"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.