Catching breaking API changes before they reach clients
A breaking change is not a mistake by itself. Sometimes a field has to go. What hurts is learning about it from a consumer's incident channel. The goal is not to forbid breaking changes; it is to make sure the owner sees them before release and the consumers hear about them before they break. This post is about the practical machinery.
What counts as breaking#
Rules differ a little between styles, but the core is shared. For a REST API described in OpenAPI, SelfDocHub treats an endpoint as breaking when:
- a parameter or a field of the main success response was added or removed;
- a type changed;
- a parameter became required;
- an enum value of a parameter was removed;
- a response field stopped being required or got a new enum value;
- the success response was removed.
Descriptions, deprecation, defaults and error responses are never breaking. For GraphQL, changing the return type of a field is breaking unless it only becomes non-null. For AsyncAPI the direction matters: for an operation that receives messages a new required field breaks the publishers, while for an operation that sends messages a removed field breaks the consumers.
The common failure is a rule that is too clever to remember, so write it down and let a tool apply it.
Diff on every publish, not on demand#
The most reliable moment to compute a diff is when the new specification is accepted. Then the result is stored, instant to
read and impossible to forget. In SelfDocHub each published version is compared with the previous one, endpoints are matched by
operationId when present (so a renamed path of the same operation is a modification, not a removal plus an addition), and the
log lists what was added, removed or modified, with field-level details for parameters and response fields at any depth, such
as items[].price.
Review it where the decision is made#
- In the pull request: publish the branch as a preview (
?branch=feature-x), so reviewers can read how the API will look, not just the code diff. The change log itself is computed when the version is published on the main branch, which is also when the version becomes current. - On the endpoint page: a Change History block shows every version that touched the endpoint, with a Breaking mark.
- In an export: add the change log to the document you send to a partner.
Tell the people who care#
Notification rules can fire for every new version with changes or only for breaking ones, by webhook, email, Telegram or
Slack. Send breaking-only notifications to the channel of the consuming teams. A message that says billing-api v1.8 removes
status from GET /invoices two days before the deploy is a conversation; the same fact after the deploy is an incident.
A small policy that works#
- Breaking changes require a new version or a deprecation period, agreed with consumers.
- Mark fields deprecated first. Deprecation is never flagged as breaking, which is what you want.
- Publish previews of risky changes from a branch.
- Send breaking-only notifications to the consumers' channel.
- Keep enough history to answer "when did this field change?" The default is 10 versions per branch.
Search the history#
When a client reports that something stopped working, the question is "what changed in the last few releases?". Searching the
change logs of a service by endpoint name or URI answers it in seconds. The same data is available to AI assistants through
the MCP server (get_version_changelog, search_changelog, diff_versions), so the assistant you ask about an endpoint can
also tell you when it last changed.
See the Change Log documentation for the complete rules.
