# API changelog and breaking change detection

Nothing erodes trust in an internal API faster than a field that quietly disappeared. SelfDocHub compares each published
version with the previous one and stores the difference, so consumers can see what changed without reading two specs side
by side, and the owner can see what they are about to break.

## An automatic change log for every version

When you publish a version that changes the specification, SelfDocHub lists the endpoints that were **added**, **removed**
or **modified**. Endpoints are matched by `operationId` when there is one, otherwise by method and path, so renaming a path
of the same operation is a modification, not a removal plus an addition.

For OpenAPI, OpenRPC and GraphQL a modified endpoint carries field-level details: for each request parameter and each
response field, at any depth (for example `items[].price`), what was added, removed or changed, and for a changed item the
old and new values. The log is computed at publish time, so reading it is instant.

## Breaking changes are flagged for you

An endpoint is marked **Breaking** when, for example, 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 or the success response was
removed. For GraphQL a changed return type is breaking unless it only becomes non-null. Descriptions, deprecation, defaults
and error responses never are. AsyncAPI uses direction-aware rules, because what breaks a publisher differs from what
breaks a consumer.

## Read it where you work

- On the **versions table** with *Show Change Log* on any version.
- On the **endpoint page**, in a *Change History* block with the *Breaking* mark for every version.
- In the **search field** above the versions table, which searches all change logs of a service by endpoint name or URI.
- In an **export**: the Export Wizard can add the change log to a DOCX, PDF, HTML or Markdown document.
- Through **MCP**: AI assistants can call `get_version_changelog`, `search_changelog` and `diff_versions`.

## Branches and a personal working version

Publishing with `?branch=feature-x` keeps a separate line of versions, so a pull request can show how the API will look
without touching what everybody else reads. A version becomes current automatically only on the service's main branch.
Each user can also choose a personal working version to read while the team is mid-migration.

## Get told before consumers find out

Notification rules send a message when a new version with changes is published, optionally only when it contains breaking
changes, by webhook, email, Telegram or Slack. Hook that into the channel of the team that owns the consuming services and
a breaking change becomes a conversation before the deploy rather than an incident after it.

## Keep as much history as you need

Old versions beyond the configured depth (10 per branch by default) are removed. Administrators and editors can also import
a specification file by hand, and anyone who can read a service can export a stored version.

---
Source: https://selfdochub.com/features/api-changelog-breaking-changes
