API as a product: why internal integrations fall apart
How the approach to internal APIs affects the reliability of the whole architecture, and why an internal client deserves no less respect than an external one.
When a company builds a public API for external partners, it is taken seriously. There is documentation, there is versioning, there is a change management process. Breaking backward compatibility is an event that gets agreed well in advance.
Internal APIs live by different rules. They get changed without warning dependent services. Documentation is skipped because "everyone's on the same team". Versioning is deferred because "we'll get to it". The result is that the same fragility the API was supposed to prevent gets reproduced inside the company.
This is one of the most common sources of operational incidents I see in growing technology teams.
What "API as a product" means
It is an approach where any API - internal or external - is designed and operated as if it had independent clients you cannot gather in one room and ask to rewrite their code by tomorrow.
In practice this means a few things. The API contract (the structure of requests and responses) is fixed and documented. Changes that break backward compatibility require an explicit decision and a transition period. API clients are notified of changes. There is versioning - even minimal versioning.
This sounds bureaucratic. In reality, it saves time: every incident caused by a broken integration costs more than a minute of contract documentation.
Why internal APIs fall apart
Three causes I see consistently.
The first is "we're all on the same team". When one service is written by team A and another by team B, it feels like you can just call someone and sort it out. This works while the teams are small and communicate well. As they grow, it stops working. Verbal agreements do not scale.
The second is no API owner. When an API has no explicit owner, anyone who touches the corresponding service changes it. There is no single decision-making point for what is acceptable to modify.
The third is no observability tooling. If an API change does not cause an immediate visible error, the problem surfaces later, at the worst possible moment. Without automated contract tests, the change goes unnoticed.
The business cost of the problem
I have seen situations where changing one internal API took down several dependent services without warning. Teams spent a day or two tracking down the cause because there was no monitoring and no documentation. That is a direct loss - in money and in trust between teams.
The slower version of the same problem: integrations start accumulating protective code layers that compensate for the upstream instability. Each such layer is debt that has to be paid eventually.
A minimum standard
Most teams do not need a complex API management system. They need a minimum standard:
- Every internal API has contract documentation - at minimum, a schema of requests and responses.
- Every API has an explicit owner - a team or person who makes decisions about changes.
- Breaking changes are agreed with clients in advance, with time to adapt.
- There is at least one integration test on critical routes.
This is not ideal architecture. But it is the difference between a system you can evolve and a system where every change is a risk.