Guide

How to notify consumers of API changes

Last checked 2026-11-023 min read

Most advice on notifying API consumers is written for public APIs: a changelog, an email list, a deprecation header. Between teams in one company the problem is different: you often do not know who your consumers are. Find them first, tell only them, give a date, and say what to change. Graphwake does the first two steps for you, from your OpenAPI spec.

ExampleEmail to admins
Weekly ownership report
Graphwake, Monday 08:00
  • 9 endpoints have no consumersOrphan
  • 1 service has no owner: catalog-apiNo owner
  • GET /orders/{id}/invoiceOrphan
Each week, admins get the endpoints that have no consumers or no owner.
On this page
  1. Why the usual channels fail inside a company
  2. Step 1: find the consumers
  3. Step 2: send it to those teams only
  4. Step 3: give a date and an action
  5. A notice template
  6. Step 4: confirm and follow up
  7. Doing this automatically
  8. Questions

Why the usual channels fail inside a company

  • Email to everyone is filtered out within a week.
  • A changelog only helps readers who go and look at it.
  • A shared channel reaches people who do not care and misses the one team who does.
  • Deprecation headers only help clients who log them.

Step 1: find the consumers

Ask, search the code you can see, and check gateway or access logs if you have them. All three miss something. A more reliable source is a list the consumers keep themselves: each team subscribes to the endpoints it calls. See API breaking change alerts.

Step 2: send it to those teams only

Message the consumer teams directly, in the channel they already read. A short message sent to five people is read; a long one sent to five hundred is not.

See who your next breaking change reaches.Paste a spec URL or add one CI step. 7-day free trial. Cancel before day 7 and you pay nothing.
Start free trial

Step 3: give a date and an action

Say when the change ships, what exactly to change, and how to ask a question. A change without a date is ignored; one without an action is postponed.

A notice template

  • What changes: GET /customers/{id} no longer returns legacyId (removed from the response).
  • Who is affected: teams that read legacyId: [list the teams].
  • When: merged on [date]; deployed on [date].
  • What to do: use id instead. Example before and after: [link].
  • Questions: reply in this thread or ask [owner].

Step 4: confirm and follow up

Keep the list of who was told and who answered. When the date arrives, check that every affected team has either moved or asked for more time.

Doing this automatically

Graphwake does steps 1 and 2 from your OpenAPI spec: consumer teams subscribe to endpoints, and a breaking change sends the alert to only those teams in Slack, Microsoft Teams or email. The alert names the endpoint and what changed; the impact score is in Graphwake, next to the change. Start a 7-day trial or read the comparison with oasdiff.

  • Consumers subscribe

    Consumer teams subscribe to the endpoints they call, so the list stays current.

  • Only those teams are told

    A breaking change reaches the subscribed teams in Slack, Microsoft Teams or email.

  • The alert says what changed

    The service, the endpoint, its owner and what changed, plus the author and pull request when it came through CI. The impact score is in Graphwake, next to the change.

  • From your spec

    It works from your OpenAPI spec: a published URL checked every 30 minutes, or one CI step.

Questions

How far ahead should I notify consumers of a breaking change?

Long enough for the slowest affected team to change and ship. Give a date, and agree on it with the teams you identified.

What if I do not know who my consumers are?

Start with the teams that answer when you ask, check logs, and have teams subscribe to the endpoints they call so the list stays current.

Pick an endpoint. See who it reaches. 7-day free trial. Cancel before day 7 and you pay nothing.

Start free trial