Overview

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
figure
Two versions of an API definition file showing one endpoint and another updated
figure
Top-level structure of an OpenAPI document structure
figure
The OpenAPI object hierarchy showing paths, path item, and operation objects
figure
A conceptual diff report shows what has changed between two versions of an API definition file.
figure
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.)
figure
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.
figure

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 the x-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.
What does the oasdiff breaking command do?It compares two API definitions and reports only the changes that are considered breaking. For example, if an endpoint was removed without deprecation, oasdiff will report it as an error indicating a breaking change.
Why are API versioning schemes important when managing breaking changes?Versioning schemes let consumers request a specific API version, which helps providers introduce changes without immediately disrupting all users. They are a key part of managing API evolution because they define how versions are exposed and consumed.
What are the main API versioning scopes described in the chapter?The chapter describes three main scopes: global versioning, per-resource versioning, and per-endpoint versioning. These differ in how broadly a change affects the API and how much of the API needs to be versioned together.
Why is a breaking change policy useful for an API provider?A breaking change policy explains what the provider considers breaking, what stability guarantees are offered, and how consumers should prepare for change. It helps set expectations, supports communication with users, and can be used to drive automated checks in the delivery workflow.
How can API design reduce the chance of future breaking changes?You can design APIs for extensibility by avoiding rigid enums when values may grow, using open-ended structures when possible, and wrapping top-level arrays in objects so new fields like pagination metadata can be added later without breaking clients.

pro $24.99 per month

  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose one free eBook per month to keep
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime

lite $19.99 per month

  • access to all Manning books, including MEAPs!

team

5, 10 or 20 seats+ for your team - learn more


Close
choose your plan

team

monthly
annual
$49.99
$499.99
only $41.67 per month
  • five seats for your team
  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose another free product every time you renew
  • choose twelve free products per year
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime
  • renews annually, pause or cancel renewal anytime
  • Automating API Delivery Automating API Delivery ebook for free
Close
choose your plan

team

monthly
annual
$49.99
$499.99
only $41.67 per month
  • five seats for your team
  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose another free product every time you renew
  • choose twelve free products per year
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime
  • renews annually, pause or cancel renewal anytime
  • Automating API Delivery Automating API Delivery ebook for free
Close
choose your plan

team

monthly
annual
$49.99
$499.99
only $41.67 per month
  • five seats for your team
  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose another free product every time you renew
  • choose twelve free products per year
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime
  • renews annually, pause or cancel renewal anytime
  • Automating API Delivery Automating API Delivery ebook for free