Chapter 02 of 13
How Often Do APIs Break?
Half of the public API contracts we compared changed within three years, two thirds of those changes break a client, and nine in ten breaking changes kept the major version.
Public APIs change their contract far more often than their version numbers admit. About half of the public API contracts we could compare changed within three years, two thirds of those changes break a client, and nine in ten breaking changes arrived without a new major version.
Those three numbers come from a study we published in September 2026. This chapter explains what each of them counts, what the word break means in them, and why the version number was no help. The full method and the open data are in the corpus study and in the public repository routebase-dev/openapi-corpus-study.
The answer in three numbers
The apis.guru directory lists public APIs and records, for 1,927 of them, the URL of the Swagger or OpenAPI file at the provider, together with a copy of that file from spring 2023. In September 2026 we fetched every one of those files again and compared it with the 2023 copy. The comparison used the same breaking-change rules Routebase applies when a team publishes a new version of its own spec.
| Question | Answer | What it counts |
|---|---|---|
| How many contracts changed within three years? | 48.9 percent | Of 493 comparable pairs, 241 changed in a way a client can observe |
| How many of those changes break a client? | 66.8 percent | 161 of the 241 changed contracts contain at least one breaking change |
| How many breaking changes came without a major version bump? | 88.8 percent | 143 of the 161 kept their major version |
| How many came with no version change at all? | 53.4 percent | 86 of the 161 carry the same version string as in 2023 |
A change counts when an endpoint, a parameter or a field was added or removed, or when a type changed. Edits to descriptions and examples do not count, because no client can observe them. The breaking subset follows the classification in what counts as a breaking change, so a removed endpoint, a removed response field, a changed type and a new required input each qualify.
The breaking changes themselves are ordinary. An endpoint disappeared in 45.3 percent of the contracts with a breaking change, and a response field was removed in 44.1 percent. On the consumer's side these are a missing route and a null value, and they appear on the day the provider deploys.
Four providers with hundreds of specs each make up more than half of the directory, so we also computed every share with each provider weighted equally. That moves the share of changed contracts to 42.0 percent, the share with a breaking change to 70.8 percent and the share without a major bump to 87.7 percent. The headline survives the weighting, and it survives leaving those four providers out altogether.
What break means in these numbers
The question of how often APIs break has two readings, and the study measures only one of them.
The first reading is an outage. The API stops answering, answers slowly or answers with server errors, and the problem ends when the provider restores service. Providers publish that number themselves as an availability target, and the arithmetic behind it is worth knowing. An availability of 99.9 percent still allows a little under nine hours of downtime a year, and 99.99 percent allows a little under one hour. We have not measured outages across public APIs, so this chapter gives no figure of its own for that reading. The provider's status page and its service level agreement are the sources for it, and the monitoring guide covers uptime, latency and SLAs.
The second reading is a contract change. The API keeps answering, often with a 200, while a field, a parameter or an endpoint that a client depended on is gone or has changed shape. Nothing recovers on its own, because the client stays broken until somebody changes its code. This is the reading the study measures, and it is the one that uptime monitoring cannot see, since a response with a missing field is still a successful response to a health check. Contract drift is the name for that gap between what the contract says and what the service does.
A third reading sits between the two. Before a contract can change, the file that describes it has to still be there. Of the 1,927 spec URLs recorded in 2023, only 1,230 still served a file in 2026, which is 63.8 percent. Another 27.0 percent answered that the file is gone. A build step that fetches a provider's spec by URL to generate a client or run a contract test fails for more than one URL in three today.
Why the version number does not warn you
Semantic versioning promises that a breaking change raises the major version, and consumers build on that promise when they pin a major or let a dependency bot wait for one. In the corpus, that promise held for 18 of the 161 contracts with a breaking change.
The rest moved in ways a consumer cannot act on. In 86 contracts the version string did not change at all, fifteen carry a lower version number today than in 2023, and eight use version strings that are not semantic versions. A client that reviews its dependencies only when the major changes would have met 143 of these 161 breaking changes without any warning from the version number.
The directory's git history shows that this is not new. Between 2015 and 2023 its update job recorded 106,083 new revisions of existing spec files, and of the pairs we could compare, 26.7 percent changed the contract structurally within a published version. Of those changes, 30.8 percent broke a client. Providers change contracts inside versions they have already published, and they have done so for as long as the record goes back.
The reason is mechanical rather than careless. A version number is typed by a person, while a contract changes whenever the code behind it changes. Nothing in a typical release process compares the new contract with the one consumers already rely on. The chapter on semantic versioning for APIs explains what the major should mean, and backward compatible API changes shows how to prove that a change stayed additive instead of assuming it.
What the numbers do not cover
Three limits shape what the study can say, and they are worth carrying along with the numbers:
- The corpus is public APIs that someone once listed in a directory, so the numbers say nothing about internal APIs, which have fewer consumers and fewer reasons to stay stable.
- The 2023 side is the directory's copy of each file rather than the provider's original, so only changes a client can observe are counted, and the directory stopped refreshing in 2023.
- A diff sees structure and not meaning. A field that keeps its type but switches from cents to whole units is breaking and invisible here, so the breaking share is a floor rather than a ceiling.
In Routebase
The study ran on the same breaking-change rules that Routebase applies when you publish a new version of a specification. Comparing two versions classifies every difference as breaking, safe or a deprecation. The release wizard warns you when the version you are about to promote breaks against what that environment runs today. A merge request between a spec branch and its draft reports the breaking changes it would introduce before anything merges.
More than half of the breaking changes in the study arrived with an unchanged version string, and that is the case drift monitors cover. They compare the live API with the contract its environment is pinned to, field by field. A field that comes back with a different type, a required field that is missing or a value outside its enumeration becomes a drift event. The event carries a first-seen date and an observation count, even when every response came back with a 200.
Contract tests ask the same question before a release instead of after it. A test case linked to a designed endpoint validates every response against that endpoint's documented schema, so a removed field or a changed type fails the run in CI before a consumer sees it. The product guides for Contract Drift and Contract Testing cover the setup, and the API monitoring page shows how drift events, alert policies and incidents fit together.
Frequently asked questions
How often do APIs break?
In a comparison of 1,927 public OpenAPI specs with their copies from three years earlier, 48.9 percent of the contracts that could be compared had changed in a way a client can observe. Two thirds of those changes, 66.8 percent, contained at least one breaking change, and 88.8 percent of the breaking changes arrived without a new major version. The numbers come from the Routebase corpus study of September 2026, and they describe public APIs listed in the apis.guru directory.
How often do APIs change?
Within three years, 48.9 percent of the comparable public API contracts in the apis.guru directory changed structurally, meaning an endpoint, a parameter or a field was added or removed, or a type changed. Edits to descriptions and examples are not counted. Weighted so that every provider counts once, the share is 42.0 percent.
Do breaking API changes come with a new major version?
Rarely. Of the 161 public API contracts with a breaking change in the corpus study, 143 kept their major version, and 86 of them did not change their version string at all. A client that waits for a major version bump before it reviews a dependency would have been warned about 18 of those 161 breaking changes.
What is the difference between an API breaking and an API being down?
An outage means the API stops answering or answers with errors, and it ends when the provider restores service. A breaking change means the API keeps answering with a 200 while the shape or meaning of the contract has changed, so a client that was correct yesterday now fails or misreads data. Uptime monitoring sees the first kind and not the second, which is why the two questions need two different measurements.
Last reviewed by The Routebase Team.