The Ai KhanLet's talk
← All case files

Case file 017Self-maintaining APIs

The problem

“A vendor changed their API overnight. We found out when our customers did.”

Solved

For
Teams whose code depends on Stripe, OpenAI or Twilio
Built
Detect → match → fix → ship. The spec and the detector are done.
Stack
Go (oasdiff) · structured change records · sandboxed fix agent
Status
In progress · Phase 0
Before: one block changed upstream, and checkout broke3D pixel film · made by me

01 · The pain

Your code didn’t change. Someone else’s did.

  • A vendor renames one field in a release note nobody on the team reads.
  • Nothing fails in testing, because the tests still talk to the old version.
  • Customers find it first, at checkout, on a Friday night.

02 · The fix

Turn a breaking change into a pull request to review.

Walk one real change through the pipeline: the project’s own test fixture, where a payment field is renamed and the login method changes. Each stage is marked built or designed.

The vendor ships a new version of their API spec. The bridge diffs it against the old one.

Spec v1.0.0
security:
  - apiKeyAuth: []
...
required: [source, amount]
properties:
  source:
    type: string
Spec v1.1.0
security:
  - oauth2Auth: [read, write]
...
required: [payment_method, amount]
properties:
  payment_method:
    type: string
ChangeEvents written (simplified)
[
  { "change_type": "field_removed",
    "target": { "field": "source" } },
  { "change_type": "other",
    "target": { "raw": "payment_method added" } },
  { "change_type": "auth_changed",
    "target": { "scheme_from": "apiKey",
                "scheme_to": "oauth2" } }
]

Notice: no “rename”. A spec diff only sees one field disappear and another appear. That is on purpose. See the hard part below.

03 · How it works

Structure first. AI only where structure runs out.

  1. Detect

    Watch each vendor’s API spec and changelog. Every change becomes a structured record: what kind of change, and exactly what it touches.

  2. Match, then fix

    Search the repos that use that vendor for the affected code. Only then does a sandboxed coding agent draft a fix, scoped to those files, and run the repo’s own tests.

  3. Ship to a person

    A confident fix becomes a draft pull request with the change explained. Anything less goes to a digest. Nothing ever merges on its own.

The hard part

A rename looks exactly like a deletion.

Compare two versions of an API and a renamed field shows up as one field gone and a new one added. A tool that guesses “these two are probably the same field” will be right most days and confidently wrong on the day it matters.

So the detector refuses to guess. It reports exactly what it can prove (removed, added) and leaves the pairing to a later step that can read the vendor’s migration notes. Seven written decision records pin choices like this one down before any code is built on top of them.

Guess “renamed” → right most days, wrong on the one that matters

Report removed + added → pair them only with proof

04 · Where it is now

Still being built, in the open.

Phase
0
Vendors in scope
3
Auto-merges
Never

Done: the architecture, the change-record format, seven decision records and the Go detector. Next: matching.