Development & Code · master area
API Implementation
The contract is the spec, the code is the implementation. Drift between the two is
adr-drift— and the most common source of broke-the-API tickets.
Owners: Developer, Tech Lead Phase it lives in: How We Build (Volume IV) The corpus principle this enacts: The artefacts the chain produces survive the conversation — the API contract is one of them.
Where it lives in the chain
- What We Build · Sequence, Schema, API — the contract is designed here
- How We Build · Service composition and DX — request-response vs event-driven implementation
How to do this
- Practice — contract first. The OpenAPI / GraphQL schema / Avro file is committed before the handler.
- Practice — contract-tested. The handler runs against the contract in CI; drift fails the build.
- Practice — versioned visibly.
/v1/gradesand/v2/gradescoexist when a breaking change ships, with a deprecation date in the contract. - Related craft — Contract Testing
What good implementation looks like
The endpoint named in domain language (POST /exams/:id/grade, not POST /api/forms). The request and response shapes match the contract exactly — no extra fields silently added, no field renamed because the developer thought of a better name. The error responses are typed and named (GradingDeadlinePassed, not 400 Bad Request). The handler is a thin shell over the domain function (gradeExam); it does not contain domain logic — it adapts HTTP to the domain.
Drift is silent. The frontend asks for gradedAt; the backend returns graded_at. The contract said gradedAt. No build catches it because the contract test was never wired up. Three days later, a CS ticket says "the timestamps are missing." That is a chain-aware bug labelled adr-drift — and contract testing exists precisely to make it loud.
Related crafts
- API Contract Design — the upstream artefact
- Contract Testing — the drift detector
- Domain Language in Code