← All provider guides

API breaking change detection: how to catch upstream breakage before it ships

detection 83,910 tracked change records 20 providers

An upstream API breaking change almost never announces itself. Of the 83,910 change records in the mendapi database, 3,151 are breaking or restrictive — and the majority were published as routine release notes, a bumped major version, or a one-line schema edit inside a spec file thousands of lines long. Detection is the problem of turning that stream into a precise answer to one question: which of these will break my code?

The three channels breaking changes arrive through

  • Changelogs and release feeds. The cheapest signal and the least reliable one: vendors under-label severity, and the phrase "breaking change" is applied inconsistently. Keyword classification is a starting point, not a verdict.
  • SDK releases. A major-version bump in an official SDK is a contract change even when the wire API is untouched — runtime requirements, removed types, renamed parameters. These break your build, not your requests, so wire-level monitoring misses them entirely.
  • OpenAPI spec diffs. The most honest channel, because the spec cannot under-report what the changelog forgot to mention. It is also the hardest to read: a single $ref re-anchor can fan out to hundreds of derived diffs, and the changes that break readers — a required field going optional, a type quietly widening — hide in the noise.

A detection system that only watches one channel has a structural blind spot. mendapi ingests all three into one change database and classifies each record with an explainable verdict.

Why default severity gates stay silent

Generic spec-diff tools ship severity levels, and default breaking gates only alert at the top level. That policy is defensible in general and exactly wrong for reader code: a property that goes from required to optional defaults to a warning, yet every consumer that reads the field breaks the day it comes back absent. In a measured comparison on 47 real Stripe spec pairs, 163 real breaking units were invisible to a default breaking gate — 58 because the engine classified them as warnings, 105 because the engine did not complete within a 15-minute timeout on 3 of the pairs. To be precise about the first group: the comparison engine detected those changes and filed them at warning level; it did not miss them. A default gate just never looks there. Full methodology and the honest-citation rules are on the when-to-use page.

Precision is the whole game

The failure mode that kills detection tools is not a miss — it is the false alarm. One wrong "this will break you" and the alerts get muted. mendapi's diff engine currently emits 32 distinct change kinds (parameter removals, type replacements, enum tightenings, required-flag flips, discriminated-union branch changes and more), and every kind is built fail-closed: when the spec evidence is ambiguous — an untyped schema, a plain union without a discriminator — the engine stays silent rather than guessing. Each kind is locked by golden-fixture regression tests with negative controls, so a rule that starts over-firing fails the build before it reaches you.

From detection to "does this hit my code"

A feed of upstream changes is trivia until it is joined against your codebase. That join is local and takes about 30 seconds, with no code leaving your machine:

npx mendapi scan
# -> findings: file, line, provider, confidence
mendapi deps --match
# -> which tracked upstream changes touch the API surfaces you use

The scanner builds a per-repo dependency map — provider × API surface × location — and matches it against the change database, so an upstream release turns into "you are affected at these lines" instead of a changelog link. For the changes that are mechanically fixable, 44 migration packs draft the fix as a reviewable diff; nothing is applied without your review, and zero network calls is the default and only mode.

Related

Every entry on this page is generated from the mendapi change database at build time and links its upstream source.