A risky API change stopped by a scanner before it reaches clients

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#

  1. Breaking changes require a new version or a deprecation period, agreed with consumers.
  2. Mark fields deprecated first. Deprecation is never flagged as breaking, which is what you want.
  3. Publish previews of risky changes from a branch.
  4. Send breaking-only notifications to the consumers' channel.
  5. 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.

Frequently asked questions

Is adding a field a breaking change?

Under SelfDocHub's rules, adding or removing a request parameter or a field of the main success response is flagged as breaking, because strict clients can fail on either. Descriptions, deprecation, defaults and error responses are never breaking.

Run it on your own infrastructure

The Free plan includes a license for one installation. Start with Docker in a few minutes, no credit card needed.