DEV Community: mendapi

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

mendapi — Sun, 02 Aug 2026 00:18:36 +0000

Originally published at mendapi.com.

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.

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

Your API provider shipped a breaking change. Here's how to find what it breaks in your code

mendapi — Sat, 01 Aug 2026 07:55:12 +0000

When Dependabot bumps a dependency, the PR is green, the tests pass, and you merge it on autopilot. Three days later something in production throws a TypeError on a code path your test suite never exercised. The upstream provider shipped a breaking change, your SDK version moved with it, and nothing in your CI caught the mismatch because your tests only cover the surface you thought to write.

This is the gap. Version bumps tell you that something changed. They do not tell you what in your code is now wrong.

The changelog is not enough

The usual advice is "read the changelog." Fine. You open the OpenAI Node SDK v3-to-v4 migration guide and it lists forty changes. Now what? You have to hold the entire diff in your head and grep your own codebase for every affected symbol, every renamed method, every reshaped response object. For one provider, on a quiet week, maybe you can. Across Stripe, Twilio, PayPal, Cloudflare, and whatever else you integrate, on a real team shipping real features, you won't. The changelog is a description of the provider's world. What you actually need is a mapping from that world onto your call sites.

That mapping is the boring, mechanical, error-prone work nobody wants to do by hand. So it doesn't get done, and you find out at runtime.

What mendapi actually does

mendapi treats this as three steps, and keeps all three local:

Spec diff. It maintains a classified database of breaking changes across major API providers, pulled from SDK release feeds and official developer changelogs. Each entry is tagged breaking / deprecation / additive / fix, so you're not drowning in additive noise.
Codebase scan. It reads that change database, detects which providers your repo actually uses (SDK imports, API hosts, env vars, not naive grep), and pinpoints the exact files, lines, and symbols a breaking change touches. It scores each finding for confidence so the high-signal ones surface first.
Reviewable fix diff. It applies deterministic migration rule packs to draft the change as a unified diff you review before anything happens. Nothing is pushed unless you explicitly ask.

The part that matters for a lot of teams: the scanner, fixer, and review CLIs contain no network code at all. Your source never leaves your machine. That's not a promise in a privacy policy, it's enforced by a test that fails the build if a network primitive shows up in those files.

The actual commands

Zero config, zero npm dependencies, Node 22+:

# In any repo — nothing leaves your machine
npx mendapi scan

You get every upstream breaking change that hits your code, with file, line, and symbol. Want it saved?

npx mendapi scan --repo /path/to/your/repo --out impact.json

Medium-confidence findings can go through an optional semantic review pass:

npx mendapi review impact.json --pending

Then draft the migration as a diff — dry-run, changes nothing on disk until you say so:

npx mendapi fix --from-report impact.json

And when you're ready to turn that into a branch and a PR-ready description (local only; --push is required to actually push and is never implied):

npx mendapi pr --repo /path/to/your/repo --from-report impact.json

The sync command is the one and only command that touches the network — it fetches the latest change feed. Everything downstream runs offline.

Wiring it into your AI coding agent

If you drive your work through Claude Code or Cursor, mendapi ships an MCP server so your agent can run the scan and read the findings itself:

claude mcp add mendapi -- npx mendapi mcp

For Cursor or any JSON-configured MCP client, drop this into .cursor/mcp.json:

{
  "mcpServers": {
    "mendapi": { "command": "npx", "args": ["mendapi", "mcp"] }
  }
}

The server runs on stdio, offline-first, zero npm dependencies. It exposes scan, deps, fix, and changes as tools that return the same structured JSON as the CLI's --json flags. So your agent can ask "what breaks if I bump Stripe" and get file-and-line answers instead of a vibes-based guess.

Where it falls short

Honesty section, because you're going to hit these:

Coverage is a set, not the universe. It watches around twenty major providers today. If your critical dependency is a niche API, it's not in the feed yet.
Rule packs are curated. The deterministic fixers exist for well-trodden migrations. For an obscure breaking change, you may get an accurate finding but no auto-generated fix — you migrate by hand, just with the exact call sites already located.
It's pre-1.0. Published on npm as mendapi v0.5.0. The change database and rule registry grow daily, and interfaces may still shift before 1.0.

None of that changes the core value: the scan tells you which of your lines break before your users do.

Try it

It's open source (AGPL-3.0), so your security team can read exactly what reads your code:

GitHub: https://github.com/mendapi/mendapi
npm: https://www.npmjs.com/package/mendapi

Run npx mendapi scan in your noisiest repo and see what a green CI has been hiding.