Internal API governance: why you need it when you have more than three teams
When a company grows to several product teams, internal integrations start creating problems. Why this happens and how to work with it.
There is a certain company size after which internal integrations start creating more problems than they solve. It usually happens somewhere between the second and fourth product team. Before that point everything holds together on knowledge - "ask Pete, he knows how it works". After that, it no longer works.
I have seen this often enough to say: this is not a problem with specific people or a specific stack. It is a structural growth problem. And it is not solved by hiring more people who "know how it works".
What starts breaking
The first symptom - every new integration between systems becomes a separate negotiation process. Team A wants data from Team B, Team B says "we will do it but the sprint is full, wait". A month later Team A has built a workaround that hits Team B's database directly, bypassing any API.
The second symptom - "unofficial" APIs appear. Someone on Team B noticed a database query, wrote a quick endpoint "for internal use", documented nothing. Now three teams depend on that endpoint and nobody knows what will happen if it is removed.
The third symptom - updating one system breaks another. Not because nobody thought about it, but because there was no mechanism for tracking dependencies.
What internal API governance actually is
This is not bureaucracy and not a department that approves every request. It is a set of agreements and tools that allow teams to integrate with each other predictably.
A minimal set that usually makes sense to start with:
API registry. Where all internal APIs live, what they do, who owns them. This can be a simple document or wiki - what matters is that it exists and is kept current.
Versioning. If an API changes in a breaking way, consumers need to know in advance. This is an agreement, not a technical magic trick.
Explicit ownership. Every internal API has an owning team responsible for its availability. Not "everyone knows", but a specific team.
Change process. How planned changes are communicated, what the notification period is, how consumers express dependency.
Why this matters for the business, not just engineers
Every time an integration breaks unexpectedly, it costs money and time. Every time a team cannot quickly understand what a system they want to change depends on - the task drags out.
Internal API discipline is not about technology. It is about the speed at which a company can change its systems without being afraid of breaking neighbours. It is about the ability to make small, confident changes rather than large, risky ones.
When to start
The usual advice is to start when the pain is already there but not yet catastrophic. If you have already lost several incidents to broken integrations or several weeks to untangling dependencies - the time is now.
A few questions to assess maturity:
- Can you answer in five minutes which systems depend on a specific service you own?
- Do you have at least a list of all internal APIs with an explicit owner?
- If a team changes a response format - how do consumers find out?
- How many times in the last six months has updating one system unexpectedly broken another?
The absence of internal API governance does not kill a company at an early stage. But it slows it down exactly when speed starts to matter.