← All breaking-change reports

136 raw removals, 17 real ones: what a spec diff over-reports

cloudflare · report · 2026-08-01 · source: change database

Between two published snapshots of the Cloudflare OpenAPI schema — 7abe88500e55 (2026-03-31) -> c92b9b0fde23 (2026-07-27) — a raw structural diff produced 6,354 change records. 136 of them were endpoint path removals, the scariest kind a diff can report: the route your code calls is simply gone from the spec.

Except 119 of those 136 were not gone at all. This is the accounting of how we know, per record, with machine evidence.

The trap in a raw diff

A path removal in a spec diff means one thing: the string key disappeared from the paths object. It does not mean the runtime URL stopped working. Specs get refactored — concrete routes collapse into templated ones, path parameters get renamed, methods get merged — and every one of those refactors shows up as a "removal" if you only look at one side of the diff.

An alerting tool that pages you 136 times for this corridor is training you to ignore it. The whole job of the curation layer is to keep that from happening without silently dropping a real break.

The ledger: 17 + 119 = 136

Every one of the 136 raw removals has an adjudicated destination. 17 were kept as genuinely client-breaking: the runtime URL or method really disappeared, with no surviving successor. The other 119 were excluded, each with machine evidence from the two spec snapshots that the surface actually survives:

- *Template consolidation — 107 records. Concrete Workers AI model routes like /ai/run/@cf/baai/bge-m3 collapsed into the pre-existing generic /ai/run/{model_name} route. The runtime URL a client sends never changed; the spec just stopped enumerating each model. The evidence rule requires the templated route to exist in both snapshots and to swallow the removed path with a literal-anchored match, so a template that is merely a shape prefix of a genuinely removed endpoint does not count. - Parameter rename, runtime-identical — 11 records. Path parameters renamed ({postfix_id} to {investigate_id} and friends). After normalizing parameter names, the route shape and the full HTTP method set are identical on both sides. No client sends the parameter's spec name on the wire. - Method superset — 1 record.* A renamed discovery route whose surviving form kept the original method and gained another. Strictly more capability, not less.

The audit tool recomputes all of this from the raw snapshots: 107 + 11 + 1 = 119 evidenced exclusions, 0 unevidenced, ledger conserved. If any future re-run finds an exclusion without survival evidence, the audit fails loud and the page you are reading fails its build gate.

What the 17 real ones look like

The kept records are the ones a client integration genuinely feels: billing usage routes gone with no successor, legacy /system secrets-store aliases withdrawn, firewall-for-ai renamed to ai-security, cloudforce-one alert routes restructured. Each entered the change database with a fixability verdict, and the mechanical renames among them are covered by deterministic migration packs — the diff you can preview and apply locally.

What we are not claiming

One-directional honesty, verbatim from the audit's stated property: every excluded removal is machine-evidenced as surviving; the keep/exclude judgment stays with the curator. The audit guarantees no real break was silently excluded — it does not claim the 17 kept records are the theoretical minimum, and a kept record may also match a rule if the curator judged it breaking anyway. And this 136-to-17 ratio is one corridor of one provider's spec history; we do not extrapolate it to other providers or other corridors. Some corridors are almost all real (an earlier Cloudflare corridor kept 14 of 14); this one was almost all noise. That variance is exactly why per-record evidence beats a ratio.

Check your own repo against this corridor

All 17 client-breaking removals from this corridor are in the change database behind this site, with fixability verdicts and migration guidance. To find out whether your repo is exposed — file and line number, no code leaving your machine:

npx mendapi scan --repo .

The full Cloudflare timeline lives on the Cloudflare breaking-change guide, which renders this same curation ledger. The parity capstones that precede this piece: 47 Stripe spec pairs head-to-head and three providers, 49 pairs, zero unexplained gaps. Methodology comparison is on the when to use mendapi page.

Detected and tracked by mendapi — Dependabot for every API you depend on. Scans run locally; your code never leaves your machine.

Related

Change data is recorded from upstream provider releases, changelogs and OpenAPI spec diffs; every article names its source.