Skip to content

ADR-0005: REST with OpenAPI and a generated client

  • Status: Accepted
  • Date: 2026-11-12

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?

  • 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.
  1. REST, with the OpenAPI document generated from the code and a TypeScript client generated from the document.
  2. GraphQL, or an RPC layer that shares types directly between server and client. Common market alternatives, listed for comparison.
  3. REST with requests written by hand in each app. Rejected by rule: the front ends talk to the API only through the generated client.

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.

  • Good, because a route that changes shape fails the type check of every screen that uses it.
  • Good, because openapi.json is 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.
  • apps/api/src/openapi.ts and apps/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.