Three Years Later: What Happened to 1,927 Public API Specs

Denny — Thu, 24 Sep 2026 13:05:36 +0000

If you integrated a public API in 2023, you probably read its OpenAPI spec, generated a client from it, and trusted the version number to tell you when the contract changed. The contract most likely did change since then, and the version number most likely kept quiet about it.

We know this because we measured it. The apis.guru directory stores 1,927 public API specs that point back to a Swagger or OpenAPI file at the provider. In September 2026 we fetched each of those files again and compared it with the copy the directory had kept since 2023. Where a contract had changed in a way that breaks a client, the major version stayed the same nine times out of ten.

What we measured

The APIs.guru OpenAPI directory is an open collection of public API descriptions, and it holds more than 2,500 APIs from 676 providers. Its update job last refreshed a spec in April 2023, so the directory is a record of how those APIs described themselves in spring 2023. For every API whose source was a Swagger 2.0 or OpenAPI 3.x file, the directory also records the URL that file came from.

We fetched those 1,927 URLs once on September 14, 2026, and parsed both the old and the new document. We then compared each pair with the same breaking-change rules that Routebase applies when a team publishes a new version of its own spec. Three limits shape what the numbers can say:

The 2023 side is the directory's copy, which differs from the provider's file in format and in small corrections, so we only count changes a client can observe.
A spec that pulls definitions from other files can't be compared reliably from one file, so those pairs are set aside.
The numbers describe public APIs that someone once listed in a directory, not internal APIs.

A third of the spec URLs are gone

Before a contract can drift, the file that describes it has to still be there. Of the 1,927 URLs, 1,230 answered with a 200 in 2026, which is 63.8 percent. Another 521, or 27.0 percent, answered with a 404 or a 410, and 122 didn't answer at all.

Where the 1,927 spec URLs recorded in 2023 led in September 2026. Fewer than two in three still serve a file, and more than a quarter answer that the file is gone. The last row collects server errors, unresolved redirects and a few rare status codes.

This is a finding about spec URLs and not about the APIs behind them, because a provider can move its description without retiring anything. For a consumer the effect is the same, though. When a build step fetches a provider's spec by URL to generate a client or run a contract test, more than one in three of those steps would fail today.

Half of the surviving contracts changed

Of the 1,230 URLs that still answered, 838 returned a document we could parse and pair with its 2023 copy. The 493 pairs that stand on their own, without definitions pulled from other files, carry the numbers in this section.

Within three years, 48.9 percent of those contracts changed in a way a client can observe. An endpoint, a parameter or a field was added or removed, or a type changed, while edits to descriptions and examples don't count. Two thirds of the changed contracts, 66.8 percent, contain at least one breaking change.

The breaking changes are not exotic. An endpoint disappeared in 45.3 percent of the affected specs, and a response field was removed in 44.1 percent. These are exactly the changes that turn into a missing route or a null value in someone else's code on the day the provider deploys.

Breaking change	Share of specs with a breaking change
Endpoint removed	45.3%
Response field removed	44.1%
Parameter removed	36.6%
Response type changed	36.0%
Required field added to the request body	17.4%
Endpoint path changed	15.5%

Nine in ten breaking changes arrive without a major bump

Semantic versioning makes a simple promise, which is that a breaking change raises the major version. Among the 161 specs with a breaking change, 143 kept their major version, which is 88.8 percent. In 86 of them, or 53.4 percent, the version string didn't change at all.

The 161 contracts with at least one breaking change, grouped by what their version number did between 2023 and 2026. Only the major bump is the signal semantic versioning promises, and it covers 18 of them. More than half kept the exact same version string, and fifteen carry a lower number today than they did in 2023.

Some of the rest moved in directions semantic versioning has no word for. Fifteen specs carry a lower version number today than in 2023, and eight use version strings that aren't semantic versions at all.

The consequence is practical. A client that pins a major version, or a dependency bot that waits for one, would have been warned about 18 of these 161 breaking changes. It would have met the other 143 without any warning from the version number.

It was always like this

The directory's git history lets us look further back than one comparison. Between 2015 and 2023, its update job committed 106,083 new revisions of existing spec files, and we compared each of them with the revision before it. Of the pairs we could compare, 26.7 percent changed the contract structurally, and 30.8 percent of those changes broke a client.

The directory stores every declared version in a folder of its own, so a new version is a new file, and nearly all of these pairs share one version number. That follows from how the directory is organised and is not a finding in itself. The finding is what providers change inside a version they have already published, which is more than one structural change in four, with almost one in three of those breaking a client.

Weighting doesn't move the headline

Four providers with hundreds of specs each hold more than half of the directory, so a share across the whole corpus risks describing those four and nobody else. We therefore computed every number with each provider weighted equally, and again without those four providers at all.

Share of re-fetched contracts	Raw	Each provider weighted equally	Without the four largest providers
Contract changed	48.9%	42.0%	50.3%
Of those, with a breaking change	66.8%	70.8%	66.7%
Breaking changes without a major bump	88.8%	87.7%	88.8%

In every column, between 42 and 50 percent of the contracts changed, and about two thirds of those changes broke something. Close to nine in ten of those breaks kept the major version, whichever way you count.

What a spec looks like before it drifts

The 2023 snapshot also shows the state these contracts were in before they changed. Only 47.6 percent of the 2,481 specs define a 4xx error response on even one endpoint, so for most of them the error format is something a consumer finds out at runtime. More than a quarter, 27.8 percent, attach no security requirement to any endpoint, and 20.5 percent define no security scheme at all.

Even the version numbers start on shaky ground, because only 31.8 percent of them follow the x.y.z shape that semantic versioning expects. We also ran the neutral core of our own built-in style guide rules, which leaves casing and other house style aside. By that measure, 98.1 percent of the specs have at least one finding, and the median spec has 13. These are Routebase's rules and therefore a convention rather than a standard.

How to catch this in your own APIs

The providers in this study aren't careless. A contract changes because the code behind it changes, and nothing in a typical release process compares the new contract with the one consumers already rely on. That comparison is cheap once it runs automatically, and it belongs in two places, at the moment a new version is published and while the API is running.

When you publish a new version in Routebase, it compares the spec with the previous version using the same breaking-change rules this study used, and it suggests the version bump those changes call for. A branch that removes a field or adds a required parameter is flagged as breaking on its merge request, and you can require an Admin or Owner to approve it before it merges. The rules and what counts as breaking are explained in API breaking changes.

For the changes that ship without a new spec version at all, drift monitors compare the live API with the published spec field by field. Contract tests run from the same spec as well. When the spec says a product carries a currency field and the live API doesn't return one, the test goes red in CI before a consumer sees the gap. The production side is covered in contract drift monitoring, and agents that work on the spec over MCP pass through the same checks.

Method

Corpus. APIs-guru/openapi-directory at commit f04b8d0bcd39c52e1cf3ad7a5fe744709832ae49, with the directory's list.json read on September 14, 2026. Contributed definitions are CC0, and definitions taken from public sources are listed under fair use.
Re-fetch. Every origin URL whose source format is Swagger 2.0 or OpenAPI 3.x, fetched once on September 14, 2026, with a 20-second timeout and no retries.
Engine. The parser, style guide rules and breaking-change detection of the Routebase product, run from a console harness without a database.
Comparison. Path placeholders are compared by position and local references are inlined before the diff, because a renamed placeholder or a moved schema is invisible on the wire. Pairs that reference other documents are left out.
Weighting. Every share is reported raw and with each provider weighted equally.
Review. Ten breaking-change verdicts drawn at random were read by hand against both documents, and the comparison rules above come from that review.
Data. Tables, pseudonymised raw data and the aggregation script are in routebase-dev/openapi-corpus-study. Data and tables are CC BY 4.0, and the script is MIT.

DEV Community: Denny