4 Breaking change checks: Managing API evolution
This chapter explains how API teams can identify and manage breaking changes as an API evolves, especially during the design and publication stages of an APIOps workflow. It shows why a simple text diff is not enough for OpenAPI files and why structural API diff tools are more useful for understanding whether paths, operations, responses, or schemas were added, modified, or removed. The discussion centers on using tools such as Tufin/oasdiff to produce readable change summaries, detect backward-incompatible changes, and support CI/CD-based checks that help teams catch problems before consumers are affected.
A major theme is that breaking changes are not just technical events but product and communication issues. The chapter defines breaking changes as changes that force consumers to update their code, contrasts them with backward-compatible changes, and explains how versioning can reduce disruption. It surveys common versioning schemes, including path-based, hostname-based, query string, custom-header, accept-header, pinned, and no-versioning approaches, and then compares different versioning scopes such as global, per-resource, and per-endpoint. It also reviews version identifiers like SemVer, CalVer, and stability labels such as alpha, beta, stable, and experimental, showing how providers combine these choices to balance flexibility, clarity, and operational cost.
The chapter also covers migration economics and policy. It explains that introducing new versions can be expensive for both providers and consumers because it requires implementation, testing, support, documentation, and client updates, and it outlines different migration patterns with different cost profiles. To keep expectations clear, it argues for publishing an explicit breaking change policy that lists what counts as breaking or nonbreaking, defines stability levels, and documents release and support schedules. Finally, it recommends practical design habits that reduce future breakage, such as treating versioning as a first-class part of the API, designing for extensibility, avoiding rigid enums when values may grow, and using JSON objects instead of top-level arrays so responses can evolve without forcing clients to break.
Points in your APIOps workflow where it’s useful to get a structured view of what has changed in your API definition files
Two versions of an API definition file showing one endpoint and another updated
Top-level structure of an OpenAPI document structure
The OpenAPI object hierarchy showing paths, path item, and operation objects
A conceptual diff report shows what has changed between two versions of an API definition file.
Jean-Jacques Dubray’s three models of API version migration. The cost of version migration for each model is illustrated in the chart. (Source: This is adapted from JJ’s original diagram available at https://mng.bz/0GON, along with the accompanying equations.)
API deprecation and sunset dates. After the deprecation date, an API isn’t recommended for use. But after the sunset date, the API is unavailable.
Summary
- A structured diff of the changes between API definition file versions helps you work out what has changed as you iterate on the OpenAPI design.
- A breaking change forces an API consumer to update their client application. OpenAPI diff tools help you automate detecting breaking changes across API definition versions.
- API versioning is a way to evolve your API while maintaining your integration with existing clients. There are several options for API versioning schemes, scopes, and identifiers to allow you to evolve your API along the axes that best fit your system. Still, consider API versioning as part of your API product interface, and keep usability in mind.
- Your breaking change policy should include the list of what you consider breaking and nonbreaking changes, your API version stability levels, and your API version schedule. You should publish your breaking change policy so your API consumers can use it to plan their integration work.
FAQ
What is the main purpose of running breaking change checks on API definition files?
To quickly detect whether changes in an OpenAPI definition are backward compatible or potentially harmful to existing API consumers. These checks help teams understand what changed, identify breaking changes early, and prevent releases that would disrupt client applications.What does an API diff tool show that a plain text diff does not?
An API diff tool shows structural changes in the OpenAPI document, such as deleted paths, modified operations, added headers, or removed schemas. This is much more useful than a line-by-line text diff when you need to understand how the API itself changed.What is the difference between the paths diff model and the endpoints diff model?
The paths model groups changes by path strings, while the endpoints model groups them by the combination of HTTP method and path. The endpoints model is often easier to read because it shows the exact operation affected, such as GET /v1/catalog/products.What is considered a breaking change in an API?
A breaking change is any non-backward-compatible change that forces API consumers to update their code to keep working. Common examples include removing an endpoint, deleting required response fields, or changing request requirements in a way that existing clients no longer satisfy.How can you ignore a planned sunset when running breaking change checks with oasdiff?
You can use thex-sunset OpenAPI extension. If the sunset date is in the past, oasdiff ignores that endpoint when checking for breaking changes, so planned removals do not fail the check.
Automating API Delivery ebook for free