The request looks harmless. A team needs the termination date of a contract to feed a new customer journey. The information already exists, somewhere, in the policy administration system. Setting up a proper integration for so little seems disproportionate: someone opens read access to the database, writes a query, and the matter is settled in three days. Everyone did good work, and did it fast.

Eighteen months later, the team that owns that system wants to restructure a table and finds it can no longer do so. It does not know exactly who reads its database, and above all what those readers assume — that this field is never empty, that this value means “terminated” and not “termination in progress”, that the update happens overnight. Every change becomes a negotiation with people who must first be tracked down. The system is not badly designed. It has simply become impossible to evolve, because a dozen shortcuts of that kind turned its internal model into a public interface, without anyone ever deciding so.

The instinct at this point is to look for a solution in tooling: what we need is a real integration platform, an API catalogue, an event bus. Those building blocks are useful and often necessary. But they do not address the cause. That is this article’s argument: integration disorder is almost never a transport problem. It is a problem of ownership and of meaning. An interface with no identified owner, no explicit definition of what it carries, no rule for change and no end date will stay unmanageable whatever technology moves it. In integration, the architectural deliverable is not the topology: it is the contract. And that contract is an asset — it is designed, maintained, retired, and it determines what the organisation will be able to change next year.

The pipe changes, the problem stays

Integration has been through several technology generations, and each presented itself as the end of the disorder.

File exchanges and point-to-point connections first linked what had to be linked, case by case. Centralised integration platforms then promised to replace that tangle with a single point of passage able to route, transform and supervise. Service-oriented architectures shifted attention towards the call contract and reuse. Web APIs and their management gateways made exposure simple, measurable and secure. Integration platforms delivered as a service, and event streaming backbones, finally brought scale, decoupling and continuous distribution.

Each of those generations produced real gains — on transport, format, security, observability. None settled the underlying problem, and the same observation repeats at every migration: on the new platform you find the same interfaces as before, re-hosted. The exchange points changed shape; neither their number, nor their opacity, nor their fragility went down.

The reason is simple. These tools handle three questions extremely well — how to move data, in what format, with what supervision — and none of the three that hurt: who owns this interface, what exactly does it mean, and how is it allowed to change. Those are questions of design and responsibility. No product settles them on the organisation’s behalf.

One failure mode deserves naming in passing, because it survives every generation: the absorption of business logic by the integration layer. It starts with a small convenience rule placed inside a transformation — an enrichment, a conditional route, a default value. It sits there because that was the fastest place to put it. A few years later, the integration layer carries business decisions no one can state any more, and the team that operates it finds itself responsible for behaviour it has no mandate over. A rule of conduct follows: the integration layer moves, translates and protects. It does not decide.

The de facto interface

Before governing its interfaces, an organisation has to admit which ones exist — and the list is always longer than the catalogue.

The direct database access above is one. The overnight export dropped on a file server is one. The exchange table shared between two applications is one. The robot replaying a user interface because no service was available is one. The “temporary” copy of a reference data set, put in place for a project and never removed, is one.

The point is not to condemn these arrangements, many of which were the only reasonable answer at the time. It is to recognise that an undeclared interface is still an interface: it creates exactly the same coupling, the same dependency and the same lock on future change as a published service — but with no owner, no description, no service commitment and no way to retire it cleanly. It has all the drawbacks of a contract and none of its guarantees.

Integration also has an uncomfortable property: it exposes data governance gaps without fixing them. The day two systems must exchange information about the same customer, somebody has to settle which of the four identifiers is authoritative and what “active customer” means on each side. These are not integration questions; they are questions of ownership and definition that the integration project discovers because it is the first work that cannot route around them. Settling them inside the mapping, by hard-coding a correspondence into a transformation, buries the problem exactly where nobody will look for it.

What an interface contract actually contains

An interface contract is not a technical description file. The description is the medium; the contract is what is promised. It covers eight points, of which only three usually appear in specifications.

An owner. A person or team that decides what the interface exposes, arbitrates change requests, and answers when it misbehaves. Without that, everything else is decoration. Ownership of the interface follows ownership of the business capability it exposes — not ownership of the platform that hosts it.

A semantics. The business definition of every element carried, in the organisation’s glossary terms rather than by its technical name. What “effective date” precisely covers, whether the amount is net or gross, in which currency, in which time zone, whether a missing value means “unknown” or “not applicable”. Most durable integration incidents do not come from an invalid format, which is caught immediately, but from a misunderstanding of meaning, which never is.

A shape. The schema, the typing, mandatory and optional fields, cardinalities, permitted values. This is the part tools can verify automatically, which is why it is the best maintained.

Delivery guarantees. Can the message arrive twice? Be lost? Arrive out of order? Those three questions have different answers depending on the mechanism, and they commit the consumer as much as the producer. At-least-once delivery — the common case in asynchronous exchange — carries a direct consequence: processing must be idempotent, producing the same result when replayed. That requires a stable key in the contract, decided together with the interface rather than added after the first duplicate posting.

A freshness. How old can the data received be? A consumer making a business decision on information whose age it does not know is taking a risk it never assessed. Expected freshness is a clause of the contract, exactly like the format.

A behaviour on error. Which codes mean what, which ones allow a retry and which forbid it, at what pace, within which rate limits. An interface that does not say whether an error is retryable leaves every consumer to invent its own policy — and uncoordinated retries are a well-known amplification mechanism during incidents.

A volume and a service level. Expected throughput, peaks, target latency, per-consumer quotas. This protects the producer, who knows what must be sustained, as much as the consumer, who knows what can be relied on.

A lifecycle. The rules for compatible change, the versioning policy, the support duration, the retirement notice. This is the most systematically omitted point, and the one that decides everything else over time. We return to it below.

A properly prepared contract answers a precise question: what can I change without telling anyone, and what must I negotiate? As long as that boundary is not written down, it defaults to the widest possible perimeter — meaning nothing can change at all.

Three questions of form, and how to settle them

The choice of integration style precedes the choice of tool, and it comes down to three trade-offs.

Synchronous or asynchronous? The right question is not performance but temporal coupling: do I need the answer to continue the action in progress? Calling a service synchronously means inheriting its availability and its latency, along with those of its own dependencies, which are often invisible from the caller. Every synchronous dependency added to a journey mechanically lowers the availability it can reach. Synchronous is justified when the answer conditions what happens immediately next — an authorisation, a blocking check, an on-demand lookup — and when refusing cleanly is acceptable behaviour. As soon as the goal is to propagate information, asynchronous is almost always the right choice: it decouples rhythms, absorbs outages and lets the consumer process at its own pace.

Command or event? A command is an intention addressed to a known recipient: do this. An event is a fact that has already happened, published without knowing who will listen: this occurred. The distinction is not cosmetic, because it designates who decides. The most frequent trap is the event that is a command in disguise: a message named “customer to be invoiced” is not a fact, it is an order — the producer has decided on the consumer’s behalf, and the coupling everyone believed removed is fully intact.

The same trade-off replays at process level. Under orchestration, one component knows the full sequence and drives the steps: the process is readable in one place, testable, traceable — at the price of a central point that knows a great deal. Under choreography, each component reacts to the events it observes: coupling is loose, but there is no longer anywhere to read the end-to-end process, which is paid for the day someone must explain to an auditor why a case stopped halfway. A reasonable split is to orchestrate end-to-end business processes that carry traceability or compliance stakes, and to choreograph the distribution of information between domains.

Direct or mediated? Point-to-point is not a sin in itself; it is its silent generalisation that costs. Two components in the same domain, under the same ownership, rarely gain from mediation. But as soon as an exchange crosses a boundary of responsibility, or the same flow is of interest to several consumers, mediation earns its keep: it provides a point of observation, allows a consumer to be added without touching the producer, and prevents every new need from creating one more link. The criterion is therefore not technological: it is organisational.

Do not expose your internal model

This is the decision with the longest-running consequences, and it fits in one sentence: the contract is not a reflection of the database.

Exposing your internal model — through direct access, a raw table export, or an interface that faithfully mirrors internal structures — amounts to granting your consumers a veto over your own evolution. The producer loses the freedom to restructure what it owns, not because it is technically hard, but because the consequences have become unpredictable. The system is frozen from the outside.

A well-designed contract is instead a deliberate projection: it exposes what the domain wants to promise the outside world, in stable vocabulary, and keeps to itself how it is internally organised. Translating between the two — between the internal model and the published one — has a real cost: a mapping to maintain. That cost buys exactly one thing, and it is worth a great deal: the right to change the inside without negotiating with the outside.

One rule completes the principle. That translation must remain a translation. If the mapping starts to decide — choosing a status, applying a threshold, arbitrating between two sources — then a business rule has left its owner and settled in a place nobody considers to be an application. That is the failure mode described earlier, and it always begins with an exception that seemed reasonable.

Changing without breaking

A useful interface changes. The question is not how to avoid that, but how to make change possible without organisation-wide coordination.

The default rule is backward compatibility: add optional elements, remove nothing, make nothing mandatory that was not, do not narrow a set of permitted values. A consumer that ignores what it does not recognise can then keep working without doing anything — provided that tolerance is itself a clause of the contract, and not an accidental property of its implementation.

The most dangerous change, however, is not the one that breaks the schema: that one is caught immediately, which is good news. The most dangerous is the change that keeps the name and alters the meaning — a status whose scope is widened, an amount that becomes net having been gross, a date that moves from one convention to another. Nothing breaks. Processing continues, and produces wrong results for months. This is precisely why semantics must sit in the contract: what is not written cannot be versioned.

When a breaking change is unavoidable, it is handled with an explicit version — accepting that running two versions in parallel costs money, which implies dating the end of the first one the day the second is published. An interface with no retirement date never dies: it accumulates consumers until it becomes untouchable, exactly like the database access at the start of this article.

That leaves the practical obstacle: you cannot retire what you do not know is being used. Two devices answer it. A consumer registry — knowing who calls what, through declaration at subscription or through traffic observation — turns an unanswerable question into a list of people to contact. Consumer-driven contract tests, where each consumer expresses in executable form what it actually expects from the interface, let the producer see what it is about to break before publishing. It is the only known way to evolve a shared interface with confidence rather than with caution.

What architecture has to hold

None of this requires reviewing every interface in a committee — that would recreate the bottleneck architecture governance is meant to avoid. The architectural role concentrates on four things.

Set the default conventions, once, so that each team does not reinvent them: permitted exchange styles and the use case for each, error format, time and currency conventions, identification rules, pagination, versioning. A convention followed by default is worth more than a standard arbitrated case by case.

Keep a catalogue of interfaces that carries the owner, not merely the technical description. A catalogue without an owner’s name against every line is an inventory, not an instrument of governance.

Reserve review for the interfaces that warrant it: those crossing a domain boundary, those leaving the organisation, those carrying sensitive or regulated data. The rest belongs to the teams, within the conventions.

Automate assurance rather than policing it: schema validation at build time, detection of compatibility breaks, execution of consumer contract tests, alerting on interfaces with no owner or no active consumer.

Useful indicators follow the same logic. The number of published APIs says nothing about the health of the integration landscape. What does say something: how many interfaces have no identified owner, how many run without anyone knowing who consumes them, how many rest on direct access to another system’s internal model, and how many still run on a version whose support has expired.

Integration is where architecture becomes real

An organisation is not characterised by the list of its applications. It is characterised by what it can change, and how fast — and that capability is written almost entirely in its interfaces. Replacing an application whose contracts are explicit, whose consumers are known and whose changes are versioned is a project: bounded scope, estimable effort. Replacing an application where nobody knows who reads what is an adventure, whose real cost only appears after the commitment is made.

That is what makes the interface contract an asset rather than a documentation formality. It is not the record of an architectural decision: it is the decision. It sets out what each domain promises, what it keeps free, and what everyone else is entitled to assume. The rest — the bus, the gateway, the format, the protocol — is only how that contract is carried. It is useful, it is replaceable, and it was never the point.