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?
Top comments (0)