<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Graphwake</title>
    <description>The latest articles on DEV Community by Graphwake (@graphwake).</description>
    <link>https://dev.to/graphwake</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4244049%2F27d32e67-d4b6-48c3-a457-be8c3c60b51f.png</url>
      <title>DEV Community: Graphwake</title>
      <link>https://dev.to/graphwake</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/graphwake"/>
    <language>en</language>
    <item>
      <title>How to tell API consumers about a breaking change (when you don't know who they are)</title>
      <dc:creator>Graphwake</dc:creator>
      <pubDate>Tue, 17 Nov 2026 13:00:00 +0000</pubDate>
      <link>https://dev.to/graphwake/how-to-tell-api-consumers-about-a-breaking-change-when-you-dont-know-who-they-are-jb0</link>
      <guid>https://dev.to/graphwake/how-to-tell-api-consumers-about-a-breaking-change-when-you-dont-know-who-they-are-jb0</guid>
      <description>&lt;p&gt;Most advice on notifying API consumers is written for public APIs. Publish a changelog, email your developer list, add a &lt;code&gt;Deprecation&lt;/code&gt; header, done.&lt;/p&gt;

&lt;p&gt;Inside a company the problem is different. You usually know &lt;em&gt;what&lt;/em&gt; you are about to change. What you often don't know is &lt;strong&gt;who calls it&lt;/strong&gt;. 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.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why the usual channels fail inside a company
&lt;/h2&gt;

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

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 1: find the consumers
&lt;/h2&gt;

&lt;p&gt;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:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Ask.&lt;/strong&gt; Post in a channel or ask around. Fast, but you only hear from the people who happen to read it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Search the code you can see.&lt;/strong&gt; If most services live in one org, search for the path or the client method:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# GitHub code search (or your own grep across checked-out repos)&lt;/span&gt;
&lt;span class="s2"&gt;"/customers/"&lt;/span&gt; &lt;span class="s2"&gt;"legacyId"&lt;/span&gt; org:your-org
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This misses services in other orgs, generated clients, and anything that builds URLs dynamically.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Check gateway or access logs.&lt;/strong&gt; If traffic goes through a gateway, group recent calls by caller:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="c1"&gt;-- example: access logs in a warehouse table&lt;/span&gt;
&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;client_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nb"&gt;count&lt;/span&gt;&lt;span class="cm"&gt;(*) AS calls
FROM gateway_access_log
WHERE path_template = '/customers/{id}'
  AND ts &amp;gt; now() - interval '30 days'
GROUP BY client_id
ORDER BY calls DESC;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This shows who called recently, but not who calls once a quarter, and a &lt;code&gt;client_id&lt;/code&gt; is not a team.&lt;/p&gt;

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

&lt;h2&gt;
  
  
  Step 2: tell those teams only
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;A short message sent to five people gets read. A long one sent to five hundred does not.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 3: give a date and an action
&lt;/h2&gt;

&lt;p&gt;Every notice needs two things:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;A date.&lt;/strong&gt; A change without a date gets ignored, because there is no reason to act now.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;An action.&lt;/strong&gt; A change without a concrete "do this instead" gets postponed, because figuring it out is extra work.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  A notice template
&lt;/h2&gt;

&lt;p&gt;Copy this, fill it in, send it to the teams from step 1:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;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].
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Five lines. Each one answers a question the reader would otherwise have to ask you.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 4: confirm and follow up
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Doing this automatically
&lt;/h2&gt;

&lt;p&gt;Steps 1 and 2 are the tedious part, and they repeat for every breaking change. We built &lt;a href="https://graphwake.com/?utm_source=devto&amp;amp;utm_medium=article&amp;amp;utm_campaign=notify-consumers" rel="noopener noreferrer"&gt;Graphwake&lt;/a&gt; to do them from your OpenAPI spec:&lt;/p&gt;

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

&lt;p&gt;It works from a published spec URL or one CI step. Steps 3 and 4, the date and the conversation, are still yours.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://graphwake.com/guides/notify-consumers-of-api-changes" rel="noopener noreferrer"&gt;graphwake.com&lt;/a&gt;.&lt;/em&gt; How does your team handle this today? A channel, a changelog, or just asking around? We'd like to hear what actually works.&lt;/p&gt;

</description>
      <category>api</category>
      <category>microservices</category>
      <category>devops</category>
      <category>architecture</category>
    </item>
  </channel>
</rss>
