Managing internal APIs as teams scale
When a five-person team grows to fifty, informal API agreements stop working. What to put in place before it starts to hurt.
Small teams run on informal agreements. "We know that field is unused, we know that endpoint is slow, we know you cannot change this one without warning." When all five of you are in one office talking every day, this works.
Then the team grows. New services appear, new people, new squads. And suddenly "everyone knows" stops working, because half the new people do not know these agreements. And a change to an API that used to be agreed in a corridor conversation in a minute now breaks three teams in production.
API governance is not bureaucracy for its own sake. It is coordination infrastructure.
What breaks first
First to break is versioning. When there is one API and one team, you can change the contract by coordinating synchronously. The moment there is more than one consumer, any change without a version becomes a risk of breakage. And this happens quietly: it looks like a "quick fix" but it breaks someone who was not part of the conversation.
The second problem is documentation. A new developer does not know which API to call, how it works, or what to do with errors. They go to ask - but the person who wrote the code has left, or is busy. Knowledge that lives in heads does not scale.
Third is ownership. When one person started a service, it is obvious who to go to with questions. When the service has been rewritten three times in two years and is now formally owned by a team of six, that is no longer obvious. In an incident, time gets spent finding the owner rather than solving the problem.
What to build
Managing internal APIs comes down to a few practices, best introduced gradually rather than all at once:
Contracts in the repository. An OpenAPI specification or equivalent - not as a formality but as a living document updated alongside the code. This is the minimum.
Versioning with a policy. When a version is deprecated, it is not removed immediately. There is a support period, there is notification to consumers. This is an agreement that needs to be written down.
Service and owner registry. One list: which APIs exist, who is responsible for each, how to reach them. This can be a simple wiki page. The important thing is that it exists and is kept up to date.
Contract change review. A change to an API that affects consumers must go through some form of agreement - even just a notification. This does not slow down development. It prevents incidents.
When to start
Not when it already hurts. Hurting means several teams are already working against mismatched contracts and there is accumulated debt.
A good moment is when the team is just starting to grow, or when a second consumer appears for the same internal API. At that point, the overhead of introducing practices is minimal and the benefit is maximum.
Signs that the moment has come:
- multiple teams are integrating with one service;
- changes in one service regularly break others;
- developers spend time asking "how does this work";
- nobody is certain who owns a specific API.
If two of the four apply to you, the moment is already here.