Catching Breaking Changes Before They Ship

When an API changes, the damage is almost always already visible — sitting in the diff between an old response and a new one. The skill isn't spotting that something changed; it's knowing which changes quietly break the clients that depend on you.

A concrete diff

Old response:

{
  "id": 1042,
  "name": "Ada Lovelace",
  "status": "active",
  "email": "ada@example.com"
}

New response:

{
  "id": "1042",
  "fullName": "Ada Lovelace",
  "status": "active",
  "verified": true
}

Four changes hide here, and they are not equal in danger.

Safe vs breaking

Safe changes are additive or widen what you accept: verifiedis a new field, and a well-behaved client ignores fields it doesn't know. Adding a value to an enum the client only sends can be safe too.

Breaking changes remove or reshape what clients already read:

• id went from number to string — a type change that breaks anyone doing arithmetic or strict comparison.
• name was renamed to fullName — every reader of name now gets undefined.
• email was removed — code that depended on it fails.

Renames are the cruelest because they read as "one field removed, one added" in a naive diff, when really it's a removal with a relocation. Narrowing an enum that clients rely on receiving is breaking for the same reason a removal is.

Rolling out without downtime

When a change has to break the contract, stage it instead of flipping it:

• Version the endpoint (a new path or a version header) so old clients keep their shape.
• Deprecate before removing. Keep the old field alongside the new one through a transition window, and announce the date.
• Emit both shapes during rollout so clients can migrate on their own schedule.
• Update types, the Zod schema, and tests together so the change is enforced everywhere at once.

When to compare

Diff two responses before you deploy any API change, when you bump a dependency that owns part of your data, and during a planned version migration. It takes a minute and turns "why is this field undefined in production" into a review comment.

Common mistakes

• Removing a field with no deprecation window. Someone is reading it right now.
• Silently changing a type. number to string compiles on the server and breaks the client.
• Assuming clients ignore extra fields. Most do; strict parsers and some codegen don't.
• Treating a rename as additive. It's a removal in disguise.

Comparing payloads by eye works for small objects and falls apart on large ones. The PayloadIQ Diff and Migration Assistant compares an old and new response, classifies each change, and flags the breaking ones — so the risky differences don't get lost in the noise.