DEV Community

Cover image for How to tell API consumers about a breaking change (when you don't know who they are)
Graphwake
Graphwake

Posted on Originally published at graphwake.com AI-assisted

How to tell API consumers about a breaking change (when you don't know who they are)

Most advice on notifying API consumers is written for public APIs. Publish a changelog, email your developer list, add a Deprecation header, done.

Inside a company the problem is different. You usually know what you are about to change. What you often don't know is who calls it. The service has been around for three years, two teams have been reorganized since, and somebody's batch job reads a field you are about to rename.

This post is a short playbook for that situation: find the consumers first, tell only them, give a date and an action, then follow up.

Why the usual channels fail inside a company

  • Email to everyone gets filtered out within a week. People learn that most of those mails are not about them.
  • A changelog only helps the readers who go and look at it. Nobody checks the changelog of an internal service before every deploy.
  • A shared channel (#api-changes, #engineering, #general) reaches lots of people who don't care and still misses the one team who does.
  • Deprecation headers only help clients that log and alert on them. Most internal clients don't.

All four share the same flaw: they broadcast. Broadcasting works when the audience is small or very motivated. Between 10 or 20 teams it turns into noise, and noise gets ignored.

Step 1: find the consumers

Before you write a single message, build the list of teams that actually call the endpoint. There are three common sources, and each one misses something:

Ask. Post in a channel or ask around. Fast, but you only hear from the people who happen to read it.

Search the code you can see. If most services live in one org, search for the path or the client method:

# GitHub code search (or your own grep across checked-out repos)
"/customers/" "legacyId" org:your-org
Enter fullscreen mode Exit fullscreen mode

This misses services in other orgs, generated clients, and anything that builds URLs dynamically.

Check gateway or access logs. If traffic goes through a gateway, group recent calls by caller:

-- example: access logs in a warehouse table
SELECT client_id, count(*) AS calls
FROM gateway_access_log
WHERE path_template = '/customers/{id}'
  AND ts > now() - interval '30 days'
GROUP BY client_id
ORDER BY calls DESC;
Enter fullscreen mode Exit fullscreen mode

This shows who called recently, but not who calls once a quarter, and a client_id is not a team.

Combine all three and you will get most of the way. The most reliable source, though, is a list the consumers keep themselves: each team subscribes to the endpoints it calls. The producer doesn't have to guess, and the list stays current when teams change.

Step 2: tell those teams only

Message the consumer teams directly, in the channel they already read: their team channel, their on-call alias, a ticket in their board. Not a company-wide channel.

A short message sent to five people gets read. A long one sent to five hundred does not.

Step 3: give a date and an action

Every notice needs two things:

  • A date. A change without a date gets ignored, because there is no reason to act now.
  • An action. A change without a concrete "do this instead" gets postponed, because figuring it out is extra work.

How far ahead? Long enough for the slowest affected team to change and ship. Agree on the date with the teams you found in step 1 rather than announcing it.

A notice template

Copy this, fill it in, send it to the teams from step 1:

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. Before/after example: [link].
Questions:      reply in this thread or ask [owner].
Enter fullscreen mode Exit fullscreen mode

Five lines. Each one answers a question the reader would otherwise have to ask you.

Step 4: confirm and follow up

Keep a simple list: who was told, who answered, who has moved. When the date arrives, check that every affected team has either shipped the change or asked for more time. Only then deploy.

That list is also useful later. When something does break, the first question in the incident review is "did they know?", and you will have the answer.

Doing this automatically

Steps 1 and 2 are the tedious part, and they repeat for every breaking change. We built Graphwake to do them from your OpenAPI spec:

  • Consumer teams subscribe to the endpoints they call, so the consumer list stays current.
  • When a pull request introduces a breaking change, the alert goes only to those teams, in Slack, Microsoft Teams or email.
  • The alert names the service, the endpoint, its owner and what changed.

It works from a published spec URL or one CI step. Steps 3 and 4, the date and the conversation, are still yours.


Originally published on graphwake.com. How does your team handle this today? A channel, a changelog, or just asking around? We'd like to hear what actually works.

Top comments (0)