# API Breaking Change Detector

> Diffs two OpenAPI versions and gets the request-vs-response asymmetry right — each finding says which client breaks and how. Never blocks a PR.

- Agent: Claude Code
- Plan: Starter (1 vCPU, 2 GiB RAM, 10 GiB disk)
- Forks: 0 · Stars: 0
- Creator: https://www.jurniti.com/creator-ca0ff2
- Tags: api, backend, claude-code, code-review, openapi, software-factory
- Requires config (you provide): ANTHROPIC_API_KEY
- Skills: api-contract-check

**To fork:** open https://www.jurniti.com/templates/api-breaking-change-detector and use the Fork action — it starts a Stripe Checkout for a new VM seeded with this template's persist disk (same flat plan price, no fork fee).

## README

# "We only added a field" — and every client got a 422

Because the field was added to a **request** body as required. In a response, that
exact change would have been perfectly safe.

That asymmetry is where API breakages come from, and a reviewer scanning a spec diff
doesn't reliably notice which side they're looking at.

## The rule everyone gets backwards

- **In a REQUEST:** adding a *required* field **breaks** existing clients. Removing
  one, or making it optional, is safe.
- **In a RESPONSE:** removing a field **breaks** existing clients. Adding one is safe.

Every finding states which side it's on, first.

## Seven breaking changes it detects

1. Endpoint removed or path changed — including trailing-slash and casing
2. Method removed from an existing path
3. Required request field added, or an optional one made required
4. Response field removed, or its type narrowed
5. Type change anywhere — `string` → `integer`, narrowed enums
6. Status code removed, or a success code changed
7. Auth requirement added to a previously open endpoint

Enum changes come back **CONDITIONAL** with the condition stated: removing a value
breaks everyone; adding one breaks clients that switch exhaustively.

## It says who breaks, not just what changed

*"A client sending the old request body now gets a 422."*

Not "field `x` changed". A diff line isn't a finding — the consequence sentence is
what makes a reviewer care.

Additive changes get a short list too. Not problems, but the surface grew, and an
undocumented addition today is a support ticket later.

## And it stops rather than half-parsing

If either spec fails to parse it reports which and stops. A partial parse *invents*
breaking changes, which is worse than no report at all.

If the contract didn't change, it says so in one line. A detector that pads its output
is one people stop reading.

## What you supply

`gh auth login` with repo read + PR comment, plus your own Claude Code login. `gh`
ships at `~/.local/bin/gh`.

Point it at a PR touching your spec, or drop `before.yaml` and `after.yaml` into
`~/apicontract/specs/`. OpenAPI 3.x and plain JSON Schema.

## Where this stops

It detects and comments when asked. It does not block a PR, set a required status,
approve, or merge — whether a breaking change is acceptable is a product decision.

It won't tell you how many clients break (it can't see who calls what), won't claim
the spec matches your implementation (it compares spec to spec unless you supply
traffic or tests), and gives the semver *rule* that applies rather than deciding your
version bump.

Verified on build: the skill, the working tree, the `NEVER_BLOCK_OR_MERGE` guard, the
request/response direction rules, all seven checks and a working `gh` are present on a
fresh fork. Running it on your own spec is yours to do.