ADR-0005: REST with OpenAPI and a generated client
- Status: Accepted
- Date: 2026-11-12
Context and problem statement
Section titled “Context and problem statement”Four front ends call the API: the office system, the driver app, the careers site and the landing site. Companies also send leads from their own systems through the lead intake API. A change in a route must not silently break a screen.
How is the contract between the back end and its callers defined and kept true?
Decision drivers
Section titled “Decision drivers”- One contract, typed from the validation schema to the screen.
- A contract change must be visible in code review.
- No HTTP call written by hand in an app.
- A public description of the API for integrators.
Considered options
Section titled “Considered options”- REST, with the OpenAPI document generated from the code and a TypeScript client generated from the document.
- GraphQL, or an RPC layer that shares types directly between server and client. Common market alternatives, listed for comparison.
- REST with requests written by hand in each app. Rejected by rule: the front ends talk to the API only through the generated client.
Decision outcome
Section titled “Decision outcome”Chosen option: 1.
Each route validates its input with a zod schema, and the same schemas produce the OpenAPI document (apps/api/src/openapi.ts). The document is versioned at packages/contracts/openapi.json. @hey-api/openapi-ts generates the client into packages/contracts/src/generated, which is committed and never edited by hand. Errors have a single body with a stable code.
Two tests keep the chain honest: apps/api/test/openapi.test.ts fails when the versioned document differs from what the code produces, and packages/contracts/test/generated.test.ts regenerates the client and compares it with the committed one. In the apps, lint rejects fetch, XMLHttpRequest and axios.
Consequences
Section titled “Consequences”- Good, because a route that changes shape fails the type check of every screen that uses it.
- Good, because
openapi.jsonis the reference of the lead intake API for integrators, with no extra writing. - Bad, because every API change has a regeneration step, and the generated files produce large diffs.
- Bad, because REST has no ad hoc queries: a screen that needs data from several resources makes several calls, or the API gains a dedicated route for it.
More information
Section titled “More information”apps/api/src/openapi.tsandapps/api/src/core/http/validation.ts: the document and the validation.packages/contracts: the document, the generator settings and the client.packages/config/eslint-react.js: the rule that forbids hand-written HTTP in the apps.- Concept pages: API contract, Error handling.
- Reference: API routes.