Two teams will build both sides of an interface in parallel. How do you verify it before either side exists?

## The problem this solves When two teams build the two halves of an interface at the same time, the traditional integration point is the first moment either learns what the other actually did. Everything before it is optimism. Agreeing the interface *first*, in an artefact both sides can check themselves against, moves that discovery to the left — into each team's own build — and is one of the more concrete shift-left practices available at a system level. ## The agreement artefact The agreement has to be more than prose in a page nobody re-reads. Written well it fixes: - **operations** and how they are addressed; - **request and response shapes**, field by field, with types, optionality and cardinality; - **field meaning** — units, precision, time zone and clock semantics, identifier format, enumerated values and what each one means; - **error responses** — which conditions produce which failure, and whether the caller should retry; - **compatibility rules** — what either side is allowed to change without ceremony (typically adding an optional field) and what counts as a breaking change. The last two are where most of the value hides. Shape mismatches are cheap to find; disagreement about what an empty list means, or whether a timestamp is the event time or the write time, is the sort of thing that survives into production. ## Two independent checks, both to the left **Provider side.** The team building the interface runs an automated check in its own build that the running implementation really produces the agreed shapes and the agreed error responses. This is the check that fails when someone renames a field or narrows a type without telling anyone — and it fails in *their* build, minutes after the change, not weeks later in someone else's environment. **Consumer side.** The team calling the interface builds and tests against a stand-in generated from the same agreed description, one that answers with the agreed shapes. Their client code, error handling and mapping are exercised before the provider is deployable at all. Because the stand-in is derived from the shared artefact rather than hand-written from a reading of it, it cannot quietly encode the consumer's misunderstanding. The pair of checks gives you the property that matters: **a unilateral change breaks a build**. Drift is detected by tooling instead of by an integration meeting. ## A worked example A clinical-trial data capture platform is being split. One team builds a participant-status service; another builds the visit form that renders the eligibility banner and unlocks the adverse-event section. Neither exists yet. The agreement pins down: `getParticipantStatus(participantId)` returns a status from a fixed set, plus `decidedAt` as an instant in UTC, plus `sourceFreshnessSeconds`; withdrawal returns the status `withdrawn` and never an error; an unknown participant returns a distinct not-found response, not an empty status. Those three decisions are exactly the ones that would otherwise be discovered late. Without `decidedAt` and the freshness value in the agreement, the provider is free to serve a cached projection and the consumer has no way to know the banner is showing a stale-cache read; withdrawal would have surfaced as an unhandled error path in the form; and an unknown participant returning an empty status would have rendered a blank banner with the adverse-event section in an undefined state. The visit-form team then builds and runs its whole client path against a stand-in on day one. The status team's own build fails the day someone changes `decidedAt` to a local-time string. ## What it does not give you This is a check on the *contract*, and the boundary is worth stating plainly in an interview: - **Semantics are not verified.** The provider can return a well-shaped status that is simply wrong or 90 seconds stale. A freshness field in the agreement lets the consumer *detect* staleness; it does not make the data fresh. - **Behaviour under load, real data volumes and real failure modes** stays outside. So do sequences: two calls whose order matters are not described by a per-call agreement. - **The stand-in can drift from reality** if the agreement is not regenerated and re-verified on both sides on every change; a stand-in nobody re-derives becomes a fiction that passes. So keep a small integrated check on the paths that matter — for this example, one that reads a real status after a real withdrawal — and let the agreed-interface checks carry the volume. ## Making it hold organisationally The technique fails for social reasons more often than technical ones. Someone must own the artefact and its change process; both teams must run their side's check as a build-blocking step rather than an optional job; and there must be an agreed answer to "what happens when the consumer needs a breaking change?" — usually an additive change plus a migration window, negotiated rather than pushed. A shared description that only one side verifies against is documentation, and documentation drifts.