# Stop announcing API changes in a shared Slack channel

Many companies with more than a handful of services end up with a channel like `#api-changes`. Producer teams post there before a breaking change. It's the responsible thing to do, and it's what most of us were taught: announce early, announce widely.

Widely is the problem. An announcement is written for everyone, so it gets read as if it were for no one in particular. What you actually need is to reach the few teams whose code breaks, and a post written for everyone is a poor way to find them.

## Why the announcement channel feels right

It's cheap: one post, no list to keep, and you don't need to know who your consumers are. It's visible, since anyone can scroll back and see what changed. And it covers you. After the incident you can point at the post and say "we announced it."

That last one is the honest reason. An announcement channel protects the sender. It does very little for the reader.

## Why it stops working

Here's the shape of it, with made-up numbers (an example, not a measurement):

```text
12 teams post in #api-changes
2 posts each a week  → 24 posts
you call endpoints of 2 teams
some of their posts touch them

→ 1 or 2 of 24 posts are yours
```

When 22 of 24 posts aren't about you, ignoring the channel is the rational choice. People skim, then they mute. The one post that was about you goes with the rest.

Every post also asks every reader to do the matching: do we call this endpoint? Most people can't answer that from memory, so they guess.

Often the team that needed the post isn't even in the channel. A new team, a team in another office, the contractor team that built the mobile app. Nobody added them.

Posted isn't received, either. The sender can't tell who read it, so "we announced it" and "they knew" turn into the same sentence in the postmortem.

Mentions make all of this worse. `@here` and `@channel` wake everyone up to tell a few. Slack itself [asks for confirmation](https://slack.com/help/articles/202009646-Notify-a-channel-or-workspace) before one goes to a channel of six or more people, and [lets owners restrict](https://slack.com/help/articles/360004635551-Manage-channel-posting-permissions-) who may use them.

## Telling is the sender's job

An announcement moves the work to the reader, who has to read everything to find what's theirs. A targeted message keeps the work with the sender, who knows what changed, and with a list of who calls each endpoint, which nobody can keep in their head.

That list is the hard part, and it's why the shared channel survives. If you don't know who calls `GET /orders/{id}`, posting to everyone is the only way to reach them. Swapping in a better channel doesn't change that; you need the list of who calls what.

## What to do instead

| Instead of | Do this |
| --- | --- |
| One channel for every change | A message in the channel each consuming team already reads |
| Every team reads every post | Each team gets only the endpoints it calls |
| The sender guesses who is affected | Consumer teams declare the endpoints they call, once |
| `@here` to get attention | A small audience that reads because every message is theirs |
| Posting after the merge | Telling them while the change is still a pull request |
| A post per update | One message per change, updated as it moves |

What that message should say, and how to wire it into Slack and Microsoft Teams, is covered in [API change notifications in Slack and Microsoft Teams](https://graphwake.com/guides/api-change-notifications-slack-teams).

## How we built Graphwake around this

[Graphwake](https://graphwake.com/?utm_source=hashnode&utm_medium=article&utm_campaign=stop-announcing) is built on this opinion. Consumer teams subscribe to the endpoints they call, and a breaking change in your OpenAPI spec reaches only those teams, in the Slack, Microsoft Teams or email channel each one picked. Everyone else hears nothing, on purpose, apart from a one-time note to a team Discovery strongly suspects is a caller.

![Example Graphwake alert in Slack for pull request #1284 on orders-api: GET /orders/{id} lost the total field and currency became required. Only checkout, mobile-app and reporting are told; search is not subscribed and stays quiet.](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/ech2uqqrns07r7y3vbab.png)

*Example: one breaking change, three subscribed teams told, one team left alone.*

A few details that matter in practice:

- The subscriber list stays current because the readers keep it. Each consumer team marks the endpoints it calls.
- Each team picks one Slack or Microsoft Teams channel, or email. We never add `@here` or `@channel`.
- With the CI step, the alert goes out while the change is still a pull request, and the same message is updated when it merges or closes.
- An endpoint nobody subscribes to counts as a blind spot in the [impact score](https://graphwake.com/impact-score). Discovery suggests teams that may use it, and a team suggested at 60% or more gets a one-time "This may affect you" note when a breaking change goes live.

## When a shared channel alone is enough

To be fair to the channel: in a small company where every engineer touches every service and there are a few changes a month, one channel already is the targeted channel. As a record, a feed of every change that nobody is expected to act on is a useful log. And for public APIs, customers outside your company aren't in your Slack anyway; a changelog and an email list reach them.

The trouble starts when the channel becomes the way consumers are supposed to find out about breaking changes.

---

*Originally published on [graphwake.com](https://graphwake.com/guides/stop-announcing-api-changes-in-slack).*

Does your company have an `#api-changes` channel? Do people actually read it, or has it quietly become a log?