When to use mendapi
mendapi sits at the intersection of four tool categories — dependency updaters, spec diff tools, changelog trackers, and codemod frameworks — without being any one of them. This page is an honest map of when to reach for which.
The one-line answer
Use mendapi when the question is “which upstream API behaviour changes actually hit my code, and what is the fix?” Use the tools below when your question is a different one.
Tool-by-tool comparison
Dependabot / Renovate (dependency updaters)
Their question: is a newer version of this package available? They open version-bump PRs and surface the changelog, but they do not read your code — whether the bump breaks you is left to your test suite.
mendapi's question: which of the behaviour changes inside that bump (or in the raw HTTP API, with no SDK involved at all) touch symbols your repo demonstrably uses — at file-and-line precision, with a previewable fix. The two are complementary: keep Dependabot for version hygiene, add mendapi for impact and repair.
Stay with Dependabot alone if your API dependencies are all thin SDKs you upgrade eagerly and your integration test coverage is strong enough to catch behavioural breaks.
oasdiff / openapi-diff (spec diff tools)
Their question: what changed between two OpenAPI documents? They are excellent at producing a machine-readable diff — if you own both spec versions and want a CI gate on your own API, they are the right tool, directly.
mendapi's question starts where a diff ends: it maintains the change history for 20 upstream providers (84,112 recorded changes, 3,224 breaking) so you do not have to collect vendor specs yourself, joins each breaking change against your codebase, and ships 47 deterministic migration packs that rewrite affected call sites. A diff is an input; a repaired repo is the output.
Use a spec diff tool directly if you are the API producer gating your own releases, not a consumer of someone else's.
Measured: mendapi's diff engine vs oasdiff on 47 real Stripe spec pairs
Because oasdiff is the closest neighbour, we measured against it instead of hand-waving. We ran both engines over every adjacent pair in Stripe's published OpenAPI history from v2100 to v2345 (47 consecutive pairs, no gaps) with a 900-second timeout per run. Every divergence was adjudicated with an independent double-sided walk of the raw specs before being counted; unadjudicated findings are never cited. oasdiff is a mature, excellent engine — the divergences below come down to severity-classification conventions and per-pair runtime, not detection failures, and this corridor covers one provider, so we do not extrapolate beyond it.
- Detection parity: on the 44 pairs where both engines completed, mendapi's engine had 0 detection gaps versus oasdiff after adjudication, and 0 false positives across every adjudicated finding.
- Default-gate visibility: 163 independently verified real breaking units in this corridor are invisible to a default oasdiff
level≥3breaking gate — 58 because oasdiff detects the same changes but classifies them as level-2 warnings (removed optional request/response properties still break existing callers and readers), and 105 because oasdiff did not complete within 15 minutes on 3 pairs across multiple independent runs, while mendapi's engine finished each of those pairs in under 17 seconds. - Alert fatigue: on one pair a single upstream schema re-anchor fanned out to 1,162 oasdiff findings; mendapi reported the same root cause as 10 canonical alerts by deliberately stopping at transitive embeds — a design choice, not a correctness claim.
Representative adjudicated cases: Stripe removing 7 request properties from POST /v1/terminal/refunds (callers sending amount break regardless of the optional flag), the checkout ui_mode enum being wholesale renamed, and payment_records repeatedly relaxing or removing card fields during its migration — each real, each silent at a default oasdiff breaking gate.
Measured across three more providers: Twilio, PayPal and Vercel
The same harness was run over the published OpenAPI histories of twilio, paypal, vercel — 49 additional consecutive spec pairs across 5 Twilio API families, 13 PayPal API families, and Vercel's platform API. Both engines completed on all 49 pairs with 0 timeouts and 0 engine errors.
- Detection parity: of 658 oasdiff breaking units, 181 matched directly and every one of the remaining 477 was classified into an explicit disposition bucket — 0 unexplained detection gaps after disposition. Several buckets are deliberate silences (format-only churn,
object-to-anywidening) under our false-positive-rate-first rule, not detections we missed. - Units reported only by mendapi's engine: 136 units in these corridors are reported only by our engine at the normalized unit level. Twilio's were human-verified true removals; the PayPal and Vercel entries were spot-verified rather than systematically re-adjudicated pair by pair, so we cite them as unit-level differences, not as an accuracy claim.
Combined with the Stripe corridor above, that is four providers and 96 real spec pairs where every oasdiff-only unit has been driven to a classified disposition with zero unexplained gaps. These corridors measure cached published spec histories; we do not extrapolate parity claims beyond these corpora and versions.
Full methodology reports
Every headline number above is recomputed from archived evidence by build gates, so the reports cannot drift from the data. The complete write-ups, with per-corridor accounting and honest-scope statements, are published as long-form reports:
- 136 raw removals, 17 real ones: what a spec diff over-reports
- 821 OpenAI spec changes, 3 that can break a client: the honest negative
- What 47 Stripe API versions taught us about breaking-change detection
- Three more providers, 49 spec pairs, zero unexplained gaps
- 20 Twilio spec pairs: 358 findings from one engine, 142 from ours, and every disagreement named
- 11 Vercel spec pairs: a real 12-endpoint removal, and the release notes that cried breaking
Changelog aggregators & API status trackers
Their question: what did vendors announce? They forward prose changelogs to your inbox. Two structural limits: they only know what the vendor wrote down (mendapi's spec-diff pipeline records breaking changes that never appear in any prose changelog), and they cannot tell you whether an announcement affects your code — every subscriber gets the same alert.
mendapi's answer is scoped to your repo: findings are evidence-gated on file:line usage, so a change to an endpoint you never call produces silence, not noise.
Use an aggregator if you want broad organisational awareness of vendor news rather than per-repo impact.
jscodeshift / ast-grep / OpenRewrite (codemod frameworks)
Their question: given a transform you wrote, apply it across a codebase. They are general-purpose rewrite engines — powerful, but the transform, the trigger, and the validation are all on you.
mendapi's migration packs bundle the trigger (a recorded upstream change), the transform (a deterministic, gold-tested rewrite), and the guardrails (staleness detection via revalidate, dry-run diffs by default, idempotent re-runs) into one unit. When a pack does not cover your case, BYO LLM drafts are the escape hatch — previewed, never auto-applied.
Use a codemod framework directly if you are doing a one-off internal refactor with no upstream-API trigger.
Decision table
Your question Reach for ------------------------------------------------- ------------------ Is a newer SDK version out? Dependabot / Renovate What changed between two specs I own? oasdiff What did vendors announce this week? changelog aggregator Apply my own custom transform everywhere jscodeshift / ast-grep Which upstream API changes break MY code, mendapi and what is the fix?
What mendapi is deliberately not
- Not an API gateway or runtime proxy — it never sits in your request path.
- Not a monitoring/uptime product — it tracks contract changes, not availability.
- Not an auto-merge bot — fixes are dry-run diffs by default; applying and pushing each require an explicit flag. A wrong PR costs more trust than ten accurate alerts.
See the security model for what never leaves your machine, and the FAQ for the short version of everything above.