← All provider guides

Self-maintaining APIs: what the term means, and which half is actually automatable

concept 84,063 tracked change records 20 providers

“Self-maintaining APIs” names a goal rather than a product category: an integration that keeps working when the provider changes underneath it, without a human noticing the changelog first. The phrase is worth pinning down, because the interesting question is not whether the idea is appealing — it is which parts of it are mechanically achievable today and which parts are still judgement calls that belong to you. This page answers both, with numbers from a working system rather than a roadmap.

The four stages, and where automation actually stops

Every integration that survives an upstream change goes through the same four stages. They differ enormously in how automatable they are.

  1. Detect that something upstream changed. Fully automatable, and mostly a data problem: watch release feeds, changelogs and OpenAPI specs, and diff them. mendapi's database holds 84,063 change records across 20 providers.
  2. Adjudicate whether the change actually breaks readers. Automatable, but this is where most tools quietly fail — a required field going optional is a warning by default severity rules and a production outage for every consumer that reads it.
  3. Locate the change in your code: which files, which lines, which call sites. Automatable, and the step that turns a changelog entry into work you can schedule.
  4. Repair the code. Partly automatable — and the honest boundary of the whole idea. A rename is mechanical. A removed capability is a design decision.

The first three stages are where “self-maintaining” is a solved engineering problem. The fourth is where the term gets oversold.

The measured split: what a codemod can and cannot do

Of the 3,228 breaking and deprecation entries currently tracked, 3,096 carry a code-fixable verdict and 132 are marked not code-fixable. That second number is 4.1% of the corpus, and it is the number that matters when someone promises a self-healing integration: those entries are cases where a provider removed a capability, changed a platform behavior, or altered a security requirement. No codemod resolves them, because the correct answer depends on what your product is supposed to do — and a tool that silently rewrote them would be doing the most dangerous thing an automated fixer can do.

For the mechanically fixable side, mendapi ships 47 deterministic migration packs. They are locked by golden-fixture regression tests with negative controls: the archived run covers 47 cases with 1,270 assertions passing and 0 failing. A pack that starts over-firing fails the build before it reaches anyone's repository.

What this looks like in practice

The loop runs locally and takes about thirty seconds. No source code leaves the machine at any stage — the only network call is the one that fetches the change feed, and it is labelled below rather than buried in prose:

npx mendapi sync  # the one network call
npx mendapi scan --repo .  # local scan: file, line, provider
npx mendapi fix --repo . --migration openai-v3-to-v4  # drafts a diff

The fix stage writes a patch for you to read, not a commit. That is a deliberate design constraint rather than an unfinished feature: an integration that repairs itself without a human reading the diff has replaced one failure mode with a worse one. The verdict on every finding is explainable, and the security model is the reason the whole pipeline is auditable — the scanner is open source precisely so a security team can read what it sends, which is nothing.

The agent-shaped version of the same loop

The reason this problem is being revisited now is that coding agents changed the economics of stage four. An agent that can read a diff, understand your codebase and make the judgement call is a plausible operator for the 132 not-code-fixable cases — provided it is handed accurate, grounded input instead of being asked to guess from a changelog URL. mendapi exposes 5 tools over MCP (scan, deps, fix, revalidate, changes), so an agent in Claude Code or Cursor can run detection and impact analysis itself and reason over structured findings. Details are on the agent integration page.

Honest limits

  • Coverage is not universal. 20 providers are tracked, and the depth varies by how well each one publishes specs. A provider with no machine-readable spec and a vague changelog is detected worse, and the per-provider guides show exactly what history exists for each.
  • Detection is not prediction. The system reports changes that have been published. It does not know what a provider will deprecate next quarter.
  • Fixes are drafts. Every patch is reviewable output. Nothing is applied, committed or pushed on your behalf.
  • The hard cases stay hard. The 132 not-code-fixable entries are not a backlog waiting to be automated — a good number of them are design decisions that should never be automated.

Which leaves a narrower but genuinely true version of the claim: the detection, adjudication and location stages can run without you, continuously, and the mechanical share of the repair stage can be drafted for review. That is what is real today, and it removes most of the work while leaving the decisions with the person who should be making them.

Related

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