An API is a contract, not a piece of code
Why the interface between systems matters more than the implementation behind it, and what that means for how you manage integrations.
When a technical team tells a business owner "we need to design the API for this", the usual reaction is a nod and a mental note to let the engineers handle it. The word itself sounds deeply technical. But the decisions made at that stage often determine whether integrations hold up for three years or require expensive rewrites every six months.
An API is not a piece of code. It is a contract between two systems - or two teams - about what data passes between them, in what shape, and under what rules. Like any contract, it is much harder to change after both sides have started relying on it.
What an API contract actually covers
A well-specified API describes three things: the shape of requests (what you can send), the shape of responses (what you will get back), and the rules around errors (what happens when something goes wrong). That last part is usually the least thought-through, and the most expensive to ignore.
When teams treat the API as implementation detail rather than contract, they tend to build tight coupling by accident. One service starts relying on a field that was never formally part of the agreement, another team renames that field, and integrations begin failing in ways that are hard to trace. The same discipline that makes external APIs stable is the reason internal integrations should be structured from the start as managed contracts, not informal connections between teams.
Why versioning is a business decision
API versioning - keeping v1, v2, v3 routes - is often treated as a developer housekeeping task. In practice it is a compatibility promise: "we will not break your integration without warning." That promise has a cost, because maintaining old versions alongside new ones takes time, but breaking it also has a cost in failed integrations and scrambled partners.
The decision about how long to support old API versions, and under what conditions to retire them, belongs to whoever owns the partner relationships, not just to the engineering team. I have seen companies lose integrations because engineers deprecated a route on a timeline nobody had communicated to the business side.
Internal APIs matter as much as external ones
Most of the conversation about API design focuses on external APIs - things exposed to third-party developers or partners. But internal APIs, the interfaces between your own services and systems, carry the same risks.
When a billing service and an ordering service communicate through an informal internal interface that nobody documented as a contract, you end up with the same fragility as with a poorly designed external API. Changes propagate in unexpected directions. Someone modifies the billing service and does not realise that three other systems depend on a specific field format.
The sign that API design went wrong
The clearest sign is when a change to one system requires simultaneous changes in five other places just to keep things running. That pattern - coordinated deploys, "you cannot release this until the other team releases that" - usually means the contract between systems was never cleanly drawn.
It does not require a major re-architecture to fix. It requires treating the interface as the primary design artifact, rather than an afterthought to the implementation.
A practical starting point
When starting any new integration - whether between your own services or with a partner - I find it useful to write down the contract first in plain language before any code is written: what does the sending side promise to send, what does the receiving side promise to handle, and what do both sides agree to do when the data does not arrive as expected.
That document, even if it is just a page, forces the important conversations early and saves time that would otherwise be spent debugging mysterious failures later.