On this page
What counts as a breaking change
A change a client built against the old spec can fail on: a removed endpoint or response field, a new required parameter or request field, a changed type, or accepted values that narrowed. Adding an optional field is usually not breaking. Graphwake counts each of these breaking cases as breaking, and always alerts on a removed response field or a removed endpoint, even an optional field or a deprecated endpoint.
Why detection is not the problem
A diff in a pull request is cheap and accurate. The author sees it. The consumer on another team does not, because they do not read that repository. By the time they notice, it is an incident.
Three ways to route an alert
| Model | How it works | Where it fails |
|---|---|---|
| Announce | Post in a shared channel or send a company-wide email | Everyone gets every change; people learn to ignore it |
| Per-consumer list | The API owner keeps a list of consumers and writes to them | The list goes stale and depends on one person remembering |
| Subscription | Each consumer team declares the endpoints it calls; a change alerts only those teams | Needs teams to subscribe once; endpoints with no subscribers are blind spots |
Right people, not more people. Subscriptions are the model Graphwake uses, and the blind-spot case is handled on purpose: an endpoint with no subscribers counts toward the impact score, and Discovery suggests teams that may be affected.
Teams subscribe
Each consumer team declares the endpoints it calls; a change alerts only those teams.
Blind spots count
An endpoint with no subscribers counts toward the impact score.
Discovery
Suggests teams that may be affected when an endpoint has no subscribers.
Before the merge
The spec comes from CI on every pull request, so the affected team can reply while the change is still a review comment.
What a good alert says
Whatever sends it, a useful alert covers four things:
- The endpoint, and what changed in it.
- Whether it breaks clients, said in words rather than a color.
- Who made the change and the pull request it came from, so the reader knows who to ask.
- Where to see the rest: how far the change reaches and which other teams it touches.
A Graphwake message in Slack or Microsoft Teams names the service, the endpoint, its owner, what changed and the severity (“Breaking change” or “Change”), plus the author and the pull request when the spec came through CI. The impact score and every team the change reaches are on the change in Graphwake, not in the message.
Before the merge, not after
An alert is most useful while the change is still a review comment. Sending the spec from CI on every pull request means the affected team can reply before the merge. The CI step in Graphwake never blocks a build; it informs.
Next steps
- How Graphwake compares with diff-only tools: oasdiff alternatives.
- To run that diff in a GitHub workflow, follow the oasdiff GitHub Action, step by step.
- To set this up by hand, see how to notify consumers of API changes, with a notice template.
- To retire an endpoint rather than change it, follow the endpoint retirement checklist.
- To make alerts part of a written change policy across teams, read API governance for multi-team orgs.
- To have it done for you, start a 7-day trial.
Questions
What is an API breaking change alert?
A message sent to the teams that depend on an endpoint when a change to it can break their clients.
Who should receive a breaking change alert?
Only the teams that call the changed endpoint, plus its owner. Everyone else should not be notified.
Pick an endpoint. See who it reaches. 7-day free trial. Cancel before day 7 and you pay nothing.
Start free trial