Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 37 ยท Design-first Workflows

API Versioning and Detecting Breaking Changes

Learn which API changes break clients, how to version OpenAPI documents and APIs, deprecate safely, and run a stand-in diff tool that classifies breaking and compatible changes.

An API is used by programs you do not control. A change that looks harmless on the server can crash a mobile app that shipped last year. Versioning is how you communicate change, and breaking-change detection is how you avoid surprising your consumers. Because an OpenAPI document describes the whole contract, two versions of it can be compared by a tool, and that comparison belongs in your pull-request checks.

Tools like oasdiff and openapi-diff do this for real; they cannot run on this site, so the stand-in below implements the core rules in Python.

Two version numbers

Do not mix these up:

  • info.version in the OpenAPI document is the version of your API description (for example 2.3.1). Use semantic versioning: patch for text fixes, minor for compatible additions, major for breaking changes.
  • The OpenAPI Specification version (openapi: 3.1.0) is the version of the file format.

What counts as breaking

A change breaks consumers if a correct client built against the old contract stops working.

Change Breaking? Why
Remove a path or operation Yes Calls fail
Rename a path, parameter or property Yes Same as remove + add
Add a required request parameter or body property Yes Old clients do not send it
Make an optional request field required Yes Same
Narrow request constraints (smaller maximum, new enum limit) Yes Previously valid input now fails
Remove a response property Yes Clients may read it
Change a type (integer to string) Yes Parsing fails
Remove a value from a response enum Usually safe Clients never receive it
Add a value to a response enum Risky Clients with exhaustive switches may fail
Add an optional request parameter No Old clients ignore it
Add a new operation No Nothing depends on it
Add a response property Usually no Unless clients use strict parsing
Change a description or example No Documentation only

Note the asymmetry: requests are inputs from clients (do not become stricter), responses are outputs to clients (do not remove or change things).

Versioning strategies

Strategy Example Notes
URL path /v1/books Obvious, cache-friendly, most common
Header Accept: application/vnd.acme.v2+json Clean URLs, harder to test in a browser
Query parameter /books?api-version=2025-01-01 Used by some cloud APIs
Date-based API-Version: 2025-06-01 Fine-grained, needs good tooling

Whatever you pick, keep one OpenAPI document per major version (openapi-v1.yaml, openapi-v2.yaml) so SDKs and docs can be generated per version. In 3.1 you can also describe the version in servers (https://api.example.com/v2).

A diff tool in miniature

The stand-in compares two versions of a small spec and classifies each difference. It covers removal of operations, new required parameters, parameter removal, response property removal and type changes, and treats new operations and optional parameters as compatible.

Python Stand-in: classify changes between two specs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The real tools check far more (headers, request bodies, nested schemas, security, enums), but the structure is the same: walk both documents and apply compatibility rules.

Breaking-change detection in CI

Terminal
# oasdiff: compare the base branch spec with the pull request spec
oasdiff breaking origin-main-openapi.yaml openapi.yaml
oasdiff changelog origin-main-openapi.yaml openapi.yaml

A typical pipeline:

  1. Check out the target branch's spec as the base.
  2. Run the diff against the PR version.
  3. If there are breaking changes and the major version was not bumped, fail the check.
  4. Attach the changelog to the pull request so reviewers see exactly what changes.
flowchart LR
  PR["Pull request<br/>changes openapi.yaml"] --> D["Diff against main"]
  D -- "no breaking changes" --> OK["Merge allowed"]
  D -- "breaking changes" --> M{"Major version bumped<br/>and approved?"}
  M -- "yes" --> OK
  M -- "no" --> F["Check fails"]

The pipeline turns "did we break anyone?" into an automatic answer.

Deprecating safely

  1. Mark the operation, parameter or property deprecated: true with a replacement and a date.
  2. Announce in the changelog and, if possible, with a Deprecation and Sunset response header (the latter is defined in RFC 8594).
  3. Measure usage in logs by client or API key.
  4. Remove only after the date passes and usage is near zero, in a new major version.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which change breaks existing clients?

    Old clients do not send the new required property, so their requests start failing.
  2. 2. What does info.version describe?

    The openapi field holds the format version; info.version is your API's version.
  3. 3. How should a deprecated operation be handled?

    A clear deprecation period lets clients migrate before removal.

Summary

  • info.version is your API's version; use semantic versioning and one document per major version.
  • Requests must not become stricter and responses must not lose or change data, or clients break.
  • Pick a versioning strategy (path, header, query, date) and stay consistent.
  • Diff the spec against the base branch in CI to catch breaking changes.
  • Deprecate with dates and replacements before removal. The Python diff is a stand-in for tools like oasdiff.

Next: Splitting and bundling large specs