# 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/change-log) documentation for the complete rules.

---
Source: https://selfdochub.com/blog/catch-breaking-api-changes-before-clients
