An interface becomes reliable when both sides know what they are allowed to assume.
A sender can produce perfectly valid output and still create failure if the receiver interprets it differently. A receiver can be well designed and still fail if it quietly depends on behaviour the sender never promised. The gap between these two expectations is where an interface contract lives.
An interface contract is the set of promises, assumptions, limits and error rules that allow two otherwise separate systems to cooperate. It belongs beneath the broader canonical owner How Interfaces Work, because it focuses on one precise question: what may each side safely rely on at the boundary?
A Contract Is More Than a Data Format
Many interface failures begin with a contract that is too shallow.
Suppose two systems agree that one field is called status and accepts the values pending, complete and failed. That defines syntax. It does not yet define meaning.
Does “complete” mean the sender finished its part? The receiver accepted the item? The customer experienced the intended result? These are different states.
A useful interface contract therefore has several layers:
- Shape: what fields, objects, signals or physical items cross?
- Meaning: what does each field or state actually represent?
- Timing: when may the receiver expect it, and how stale may it be?
- Cardinality: can the same event arrive once, many times or not at all?
- Error behaviour: what happens when the sender cannot fulfil the normal promise?
- Responsibility: at what point has custody or obligation moved?
The Sender Promise
The sender side of a contract says, in effect: if you receive this from me, you may rely on these facts.
A logistics system may promise that every dispatched parcel has a unique identity, valid destination and custody record. A bank may promise that a particular message means an instruction passed defined validation. A teacher may promise that a diagnostic result refers to performance under named conditions rather than an undefined impression.
The stronger the promise, the more work the sender usually has to do before emitting the output.
The Receiver Assumption
The receiver side says: if the sender fulfils the published promise, this is what I will do next.
This assumption should be no stronger than the contract.
If a sender promises only that a payment request was accepted for processing, the receiver must not treat that as proof of final settlement. If a teacher reports that a learner can complete familiar questions, the next teacher should not silently upgrade that into “can transfer the method independently.”
Many integration failures are therefore not broken code or broken people. They are assumption inflation: the receiver believes the interface guarantees more than it actually does.
Preconditions and Postconditions
A clean interface contract often separates what must be true before the interaction from what the sender guarantees afterward.
- Precondition: what must the caller or sending system supply correctly?
- Postcondition: if the operation succeeds, what new state is guaranteed?
This links directly to How Preconditions Work and How State Validation Works. The interface sits between them: verify what may enter, then define what may be claimed after the transition.
Error States Are Part of the Contract
Weak contracts explain success and leave failure vague.
A strong contract defines failure classes clearly enough that the receiver knows what to do next.
- invalid request: repair the input before retrying;
- temporary unavailable: retry may be useful later;
- permission denied: different authority is required;
- conflict: current state changed and must be reconciled;
- partial success: some effects occurred and blind retry may be unsafe.
Error detail is not decoration. It changes the repair path.
The Contract Ends Somewhere
An interface contract cannot promise the whole world.
A delivery carrier can promise accepted custody and defined delivery attempts. It cannot guarantee that the recipient will be home unless that condition is part of a broader service design. A payment rail can carry instructions reliably without guaranteeing the commercial quality of the purchase that motivated the payment.
The boundary of responsibility must therefore be visible. Otherwise the receiver assigns end-to-end expectations to a component contract.
Physical Interfaces Have Contracts Too
The idea is not limited to software.
A shipping container interface defines dimensions, lifting points, strength and handling expectations. A power socket defines geometry, voltage and connection behaviour. Railway platforms, loading docks and mechanical couplings all work because both sides conform to a shared boundary specification.
Standards are contracts scaled across many participants. See How Standards Work and How Interoperability Works for the wider system.
Human Interfaces Need Explicit Contracts More Than We Think
Human organisations often rely on interface contracts that are unwritten.
A teacher assumes the previous teacher covered a topic. A hospital assumes a referral contains the decisive history. A department assumes another team will monitor the exception after handoff.
Because people are flexible, these systems can survive ambiguity for a long time. The cost appears as rework, chasing, duplicated checking and individual heroics.
When a process depends repeatedly on someone “just knowing,” the interface contract may exist only inside people’s memory.
Worked Example: A Student Handoff
Imagine a Primary 6 learner entering Secondary 1 Mathematics.
The receiving teacher sees prior grades. What does the grade contract actually guarantee?
It may support claims about performance on a particular syllabus and assessment under particular examination conditions. It does not automatically guarantee fluent algebraic notation, independent planning or perfect prerequisite retention months later.
A better educational interface distinguishes what the prior signal proves from what still needs fresh validation.
Worked Example: Logistics Custody
A warehouse hands a shipment to a carrier. The contract should answer:
- what identifies the shipment;
- what condition it is expected to be in;
- when custody transfers;
- what counts as acceptance;
- how shortages or visible damage are recorded;
- what evidence closes the handoff.
Without these rules, the strongest warehouse and strongest carrier can still create an unowned gap between them.
Contract Tests
Interface contracts should be tested at edges, not only at the happy path.
- What is the smallest valid input?
- What malformed input must be rejected?
- What happens when optional information is missing?
- What happens when the receiver is slow?
- Can an event arrive twice?
- What happens when the sender changes version?
- Which promises are stable across upgrades?
- What evidence proves the receiver accepted custody?
The CivDJ Rotation
Run the contract from three directions.
- Forward: sender produces output → interface checks → receiver consumes it.
- Backward: start from successful receiver action and ask what contract promises had to hold upstream.
- Rotate: compare what sender, receiver, maintainer and end user each think “success” means.
If the four viewpoints disagree, the contract is probably carrying hidden assumptions.
Civilisation Is Built From Contracts at Boundaries
Modern civilisation relies on specialisation. Specialisation requires interfaces. Interfaces require promises that survive organisational, technical and human boundaries.
The better the contract, the less each side needs intimate knowledge of the other side’s internals. That is what makes modularity and scale possible.
An interface contract is a carefully bounded promise: enough certainty for the receiver to act, without pretending the sender owns the whole world beyond the boundary.
Continue through How Interfaces Work, How Cross-System Handoffs Work and the master How X Works hub. The next problem is deeper than format: two sides can exchange the same fields and still disagree about what they mean.