Internal APIs as the backbone of IT architecture
Why companies that treat internal APIs as technical details pay a steep price with every integration and every change.
When a company buys a new system, the first question is usually: "How do we integrate it with what we already have?" The second: "How long will it take?" And almost never comes the third, most important question: "Why does every next integration cost more than the previous one?"
The answer to the third question is almost always the same. The systems in the company do not talk to each other by common rules. Every connection is a separate agreement, a separate format, a separate chunk of maintenance code. Over time this becomes a web that nobody can change without risking something breaking.
Why this is an architecture problem, not an integration problem
Each point-to-point integration seems like a reasonable decision in the moment. Need to link CRM to email - write a connector. Need to pass orders from the online shop to the warehouse system - write another. Need to send customer data to analytics - and another.
Three years later the company has dozens of these connectors. When it is time to replace the CRM, it turns out eight systems are connected to it, each in a different way. Changing a single field in the CRM breaks something unpredictably.
This is not the fault of a specific developer or a specific project. It is the absence of an architectural decision about how systems should exchange data.
What an internal API gives you as an architectural choice
When a company decides to build internal interactions through explicit API contracts, several things change at once.
Clarity. Every interaction between systems is documented and predictable. A new developer or integrator does not guess the data format - they read the contract.
Isolation of changes. If something changes inside one system, it does not automatically break everything connected to it - as long as the contract stays stable. This is a fundamental property that lowers the cost of change.
Ability to manage dependencies. When interactions are explicit, they can be mapped, analysed, and simplified or rerouted by deliberate decision.
Observability. An API is a natural place for logging, monitoring, and measuring usage. In a mesh of direct integrations, none of that exists.
Where companies usually get stuck
Moving to an API architecture is not a technical project - it is an organisational decision. Companies get stuck for two common reasons.
The first: no answer to "who owns this API?" Writing an API and maintaining it as a product are different things. If no one is assigned responsibility for an API, it degrades the same way any unmaintained code does.
The second: companies underestimate the cost of versioning. An API changes, while the systems consuming it change at a different pace. Managing that gap requires discipline that is often absent.
Both problems are solvable. But they need to be named before implementation starts.
How to start moving in this direction
I do not advise companies to stop and rewrite all their integrations from scratch. That almost never works as planned.
A more useful approach: at the next integration project or when changing an existing one - deliberately build it as an API contract with documentation and an assigned owner. It takes a little more time in the moment but creates a template.
A few questions worth asking at the next integration project:
- Is there documentation for this API that a new developer can read without explanation?
- Who will be responsible for backward compatibility when this API changes?
- How will we know if something in this interaction breaks?
- If we need to add another consumer tomorrow - will that take days or weeks?
The answers to these questions predict how much the next three years will differ from the last.