DEV Community: Abhinav Sharma

Ten checks to run before you merge an API change

Abhinav Sharma — Wed, 21 Oct 2026 20:43:29 +0000

Most API breakage does not come from a dramatic rewrite. It comes from a small change that looked safe in the pull request. Here are ten checks I run before merging any change to a REST API. Each one is about the consumer, not the spec, because a spec diff tells you what changed and not who will feel it.

1. Renamed or removed response fields

A rename is a removal plus an addition, from the point of view of every consumer. Search downstream code for the old field name, not just the new one. Optional fields are the worst case: the spec allows them to be absent, but some consumer has started to depend on them.

2. Type and format changes

String to integer is obvious. Date to datetime is not. Strict deserializers fail even when the values look the same to a human.

3. New required parameters or fields

Any new required input breaks every caller that does not send it yet. Make it optional first, or version the endpoint.

4. Enum and constant changes

Adding a value breaks clients that validate exhaustively. Removing one breaks clients that rely on it. Check both directions.

5. Status code and error shape changes

Callers branch on status codes and parse error bodies. Change either and behaviour changes, even if the happy path is identical.

6. Authentication and authorization changes

A new scope, a shorter token lifetime or a stricter role fails at runtime, not in review. Adding an API key requirement to an endpoint is a good example: the diff is one line, and every keyless caller gets a 401.

7. Pagination and defaults

A different default page size, sort order or filter changes results for every consumer that relied on the old default without ever saying so.

8. Deprecation and sunset signals

If you plan to remove something, send Deprecation and Sunset headers first, then confirm someone actually saw them before the removal date.

9. A consumer inventory before merge

Know which services, jobs and third parties call the endpoint you are changing. Missing data is not zero usage. If you cannot list the consumers, treat that as a review task.

10. A migration window and a rollback path

There is no universal number of weeks. Agree the window with the teams affected and keep a way back.

Using it

Print the list, or copy it into your pull request template. The ones that bite most often in my own small test cases are 1 (optional fields) and 6 (auth), which a spec diff tends to report as informational.

I put the same list in a one-page PDF: https://impactgate.in/api-change-safety-checklist.pdf

I am building Impact Gate, a warn-only pull request check that lists which consumers an API change can affect, with file and line. There is a read-only demo at https://impactgate.in .

Which check would you add as number 11?

The two API changes oasdiff let through, and why consumers still break

Abhinav Sharma — Fri, 16 Oct 2026 07:49:22 +0000

Last week I ran oasdiff on 13 labelled API change cases I wrote. It caught 8 of the 10 breaking ones (oasdiff v1.33.0, default ERR-level gate) and missed 2. This post is about those 2, because they point at a gap that a spec check alone does not cover: the difference between a change that is breaking in the spec and a change that breaks someone.

Quick context on the cases, so you can judge how much weight to put on this. They are synthetic. One small Orders API, 13 before/after OpenAPI specs, seven made-up consumer services, labels written by me. 10 are breaking changes, 3 are controls (a new optional field, a new endpoint, a renamed path parameter). oasdiff v1.33.0 with --fail-on ERR raised no false alarms. Everything is public: https://github.com/impact-gate/impact-gate-benchmarks

The two it let through

1. Removing an optional response field.
In the spec, a field that is optional in a response is allowed to be absent. So removing it can reasonably be reported as informational. But if a consumer reads that field, for example to show a customer's phone number, the consumer now gets nothing where it used to get a value. The spec said "optional". The consumer treated it as "there".

2. Adding an API key requirement to an operation.
Adding a security requirement is also reported as info by oasdiff, and that is a defensible choice for a diff tool: the spec changed, the API did what it was told. But a consumer that calls the endpoint without a key now gets a 401. For that consumer, the change was breaking on the day it shipped.

Neither report is wrong. A spec diff answers "what changed in the contract". The question a reviewer actually has on a pull request is different: "who will this hurt?"

Why this matters on a pull request

When you review an API change, the spec diff tells you the shape of the change. It does not tell you:

which other services call this endpoint,
which of them read the field you are removing,
which of them call without the header you are about to require.

In a small team you carry that in your head. In a larger one, you find out after the deploy.

What Impact Gate does about this

Impact Gate is a warn-only check that comments on the pull request with the services and code that depend on the endpoint you are changing. Each consumer it lists comes with the file and line where it was found.

There is a live demo on real pull requests you can open yourself: https://impactgate.in . No signup is needed to look around.

I want to be careful about claims. Scoring Impact Gate itself on these 13 cases is not published yet, so I am not claiming it catches the two above. Automated consumer scoring and real-project cases are next*.

* Planned, not available yet.

Where I would like to be wrong

If you disagree with a label, open an issue on the repo. If you have a case where a spec diff passes and a consumer still breaks, I would like to add it. And if you run a different tool against the cases, the runner is TOOL_CMD="your-tool" bash scripts/run.sh.

Question for people who maintain more than one service: how do you find out today who depends on an endpoint before you change it?

I built 13 labelled OpenAPI breaking-change cases, and oasdiff missed 2 of them

Abhinav Sharma — Fri, 09 Oct 2026 06:23:43 +0000

I'm working on Impact Gate, a warn-only PR check that tells you which consumers an API change can affect. Before claiming anything about it, I wanted a public set of cases anyone can run. So I wrote one: github.com/impact-gate/impact-gate-benchmarks.

What it is: 13 before/after OpenAPI specs on one small Orders API, each with a label (breaking or not) and two made-up consumers, one of which is affected or neither is. 10 breaking changes, 3 controls (a new optional field, a new endpoint, a renamed path parameter).

What I ran: oasdiff v1.33.0 with --fail-on ERR. It caught 8, missed 2, raised no false alarms. The misses: removing an optional response field, and adding an API key requirement to an operation. oasdiff reports both as info, which is a defensible choice for a spec diff. But a consumer that reads that field, or calls without a key, breaks all the same. That gap between spec-level breaking and consumer-level breaking is what I want to measure.

Limits, plainly: the cases are synthetic, I wrote the labels myself, and 13 cases proves nothing about real-world accuracy. Next: real-project cases and automated consumer scoring. If you disagree with a label, open an issue, I'd like to be wrong in public. To score your own tool: TOOL_CMD="your-tool" bash scripts/run.sh.