Internal API changelogs: what changes for the other team
5 min read
Every other article in this hub assumes the caller of an API is outside the company: a customer’s engineer, a partner, someone who found the docs on their own. Plenty of APIs have a different caller entirely, a team down the hall or two floors away, and that changes the calculus for what a changelog owes them, because a Slack message can reach them and a support ticket usually never gets filed at all. Most teams conclude from this that internal APIs do not need a changelog. What they actually need is a different one.
What makes an internal API’s changelog different from a public one?
The audience is reachable directly, which removes the reason most public API changelogs exist: broadcasting to callers you cannot individually contact. An internal API’s owning team usually knows exactly which other teams call it, sometimes down to the specific service. That makes a targeted message, not a public feed, the natural default, and it is why internal APIs so often end up with no changelog at all: the owning team pings the two or three teams they remember are affected, on the assumption that covers everyone.
| Public API changelog | Internal API changelog | |
|---|---|---|
| Who reads it | Any external caller, mostly unreachable directly | A small, usually known set of internal teams |
| Default channel | A page and a feed | A message to the calling teams, ideally also a page |
| Biggest risk | A caller misses the entry entirely | The owning team forgets a caller they don’t remember exists |
| What replaces “we didn’t know who calls us” | Nothing; publish broadly | An actual registry of callers, kept current |
Why does “we’ll just tell the teams that call us” break down?
Because the set of callers is never as small or as static as the owning team remembers. A service built for one consumer picks up a second caller six months later, through an integration nobody announced, and the owning team’s mental list of “who calls us” is now wrong without anyone noticing. The failure is ordinary and common, the default outcome of relying on memory instead of a record, not a sign anyone was careless. What is a breaking change covers how to decide whether a given API change counts as breaking in the first place; the internal case adds a second, harder question on top of that one, which is knowing who to tell.
Does an internal API need a public-style changelog page at all?
Usually yes, even though the primary channel is direct. A page gives the direct message something
to link to, so the notification can be short (“breaking change to /v2/accounts, details here”)
instead of trying to carry the full explanation in a chat message that will scroll away. It also
becomes the thing a new team, or a team that missed the direct message, can check when their
integration breaks and they are trying to work out why. The page does not need to be polished or
public-facing; it needs to be linkable and it needs to outlive the Slack thread that announced it.
Who actually maintains the list of callers?
The owning team, and it has to be treated as a real artifact, not tribal knowledge. The cheapest version is a file in the API’s own repository, a short list of consuming services and an owner per entry, updated whenever a new integration is built, the same discipline as any dependency declaration. The alternative, asking around before every breaking change, works until the one time someone forgets to ask the right person, and an internal API breaking silently for one team is a smaller incident than a public one but it is still an incident, usually discovered by that team’s own on-call rather than by the API owner.
# consumers.yml
- service: billing-service
owner: "#team-billing"
since: 2026-03-01
- service: reporting-pipeline
owner: "#team-analytics"
since: 2026-06-14A file like this turns “who do we need to tell” from a question into a lookup. Tools built for exactly this problem, like Backstage’s service catalog, model APIs as first-class entities with declared consumers for the same reason: once an organization has enough internal services, nobody’s memory of who calls what stays accurate on its own, and something has to hold the record instead. The docs for whichever tool you already run internally are usually the right place to check before building a bespoke one.
What belongs in an internal changelog entry that a public one wouldn’t need?
More operational specificity, because the reader is another engineer who will act on it within the same infrastructure, not read it as a summary. Which environments the change is live in and when, since internal services often promote through stages a public caller never sees. Whether the change requires a config or client-library bump on the consumer’s side, stated as a command if there is one. And, because internal callers can often coordinate the fix directly with the owning team, a named contact rather than a support channel: “ping @maria if this breaks anything” is a completely reasonable line in an internal entry and a strange one in a public API changelog.
Does this apply the same way to a changelog inside a monorepo?
It sharpens the same problem rather than replacing it. Monorepo changelogs covers when a package needs its own changelog; an internal API that is one package among several in a monorepo still needs its consumers tracked explicitly, because being in the same repository as its callers does not mean those callers will notice a change unless something tells them to look. Proximity in the repo is not the same as proximity in attention.
FAQ
Does an internal-only API need a changelog if it only has one caller? Barely, and a direct message to that one team usually covers it. The changelog earns its keep once there is more than one caller, or once the caller list has ever surprised the owning team, because that is the sign memory alone is no longer reliable.
Should internal API changes go through the same review as public ones? The wording can be lighter, since the reader is a colleague rather than an external caller, but the decision of whether a change is breaking should get the same care either way. An internal caller still has production code depending on the old behavior.
How do you find out who calls an internal API if no one tracked it? Server logs or a service mesh’s traffic data are the honest answer if a consumer registry was never kept; treat that discovery as the moment to start one, not as a one-time cleanup.
Is a Slack message enough, or does an internal change need a formal changelog entry too? Both, for anything that isn’t purely additive. The message is what gets read in time; the entry is what a team troubleshooting weeks later, who never saw the message, can still find.
The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.