API contract and generated client
This page explains how the contract between the API and its callers is defined and kept true. It is part of section 9 of the arc42 template. The decision and the options that were considered are in ADR-0005.
The problem
Section titled “The problem”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. A route that changes the shape of its answer must break the build of the screens that use it, not a screen in front of a user.
The rule
Section titled “The rule”- Every route declares its input and its answers as schemas, in the code of the route.
- The OpenAPI document is generated from those schemas and versioned in the repository. Nobody writes it by hand.
- The front ends call the API only through the client generated from that document. No app writes an HTTP request to the API by hand.
How the code applies it
Section titled “How the code applies it”The contract is produced in a chain. Each link is generated from the one before it.
| Step | What happens | Where |
|---|---|---|
| 1. The route | A controller declares the body, the query and the path parameters with zod schemas (@Body({ schema }), @Query({ schema }), @Param(name, { schema })), the success answer with @ApiOkResponse({ standardSchema }), and the error codes it can return with @ApiErrorResponses(...). |
apps/api/src/modules/<module>, apps/api/src/core/openapi/api-errors.ts |
| 2. Validation | One pipe validates every declared schema before the handler runs. An invalid request answers 400 validation_failed, with one issue per field. |
apps/api/src/core/http/validation.ts |
| 3. The document | buildOpenApiDocument builds the OpenAPI document from the controllers. It runs without a database or Redis, so the result does not depend on the environment. pnpm --filter @ochema/api openapi writes it to the versioned file. |
apps/api/src/openapi.ts, apps/api/src/openapi-cli.ts, packages/contracts/openapi.json |
| 4. The client | pnpm --filter @ochema/contracts generate runs @hey-api/openapi-ts over the document and writes the types and one function per operation. The output is committed and never edited by hand. |
packages/contracts/openapi-ts.config.ts, packages/contracts/src/generated |
| 5. The apps | An app points the client at the API once, with configureApiClient, and calls the generated functions. In the office system and the driver app every call goes through request, which returns the data or throws an error with the stable code. |
packages/contracts/src/index.ts, packages/app-kit/src/request.ts |
The name of each generated function is the name of the controller method: the route GET /auth/me is the method getMe in the API and the function getMe in the client. A route that is renamed or changes a field fails the type check of every screen that uses it.
The careers site is rendered on the server. Its pages and its own endpoints call the API through the same generated client (apps/careers/src/lib/api.ts), and the browser of an applicant talks only to the careers site, never to the API.
Conventions every route follows
Section titled “Conventions every route follows”| Convention | What it is |
|---|---|
| Authentication | An httpOnly session cookie, sent with credentials: 'include'. The document declares the cookie of a deployed environment (__Host-ochema_session) and the one of local development, and the same pair for the platform panel. See Authentication and permissions. |
| Routes without a session | Public pages and links live under /public and are identified by a token or by the address of the company. The lead intake API, POST /public/v1/leads, takes Authorization: Bearer <key> and is the only route of the document with a version in its path. The webhooks of the SMS and email providers, under /public/v1/webhooks, are not part of the document. |
| Errors | One body for every status from 400 to 503, with a stable code. See Error handling. |
| Lists | The lists of registers are paged by an opaque cursor, never by page number, so a list stays correct while rows are added. |
| Request id | Every answer carries X-Request-Id. A caller may send its own, and the API echoes it. |
| Active company | The office system sends the company a browser tab shows in the X-Ochema-Tenant header. If another tab switched company, the API answers 409 tenant_changed instead of serving data the tab does not show (packages/app-kit/src/tenant-header.ts, apps/api/src/core/auth/guards.ts). |
| Request limits | A route with a limit answers 429 rate_limited with Retry-After. |
At the time of writing, packages/contracts/openapi.json describes 535 operations in OpenAPI 3.0, with the API at version 0.1.0. The current list, by module, is the generated page API routes. Outside production, the API also serves the document as an interactive page at /docs of its own address.
What guarantees it
Section titled “What guarantees it”| Guarantee | Enforced by |
|---|---|
| The versioned document is what the code produces. | apps/api/test/openapi.test.ts builds the document and compares it with packages/contracts/openapi.json. |
| Every operation documents the single error body. | The same test checks every operation of the document. |
| The committed client is what the document produces. | packages/contracts/test/generated.test.ts generates the client into a temporary folder and compares it, file by file, with packages/contracts/src/generated. |
| No app calls the API by hand. | The lint rules no-restricted-globals and no-restricted-properties reject fetch and XMLHttpRequest, and no-restricted-imports rejects axios, in apps/web and apps/driver (packages/config/eslint-react.js, tested by packages/config/test/http-rules.test.js). The fetch and XMLHttpRequest rules also cover the .astro pages and the server files of apps/careers and apps/landing. |
| Every error code has a text on screen. | apps/web/test/i18n.test.ts reads the codes from the document and fails when one has no English text. |
Known limits
Section titled “Known limits”- One version. The contract has no version negotiation. The API and the front ends are released together, and a breaking change is a change of both. Among the routes of the document, only the lead intake API carries a version in its path.
- Regeneration is a manual step. After a route changes, the document and the client are regenerated with the two commands above. Forgetting it fails the tests, not the build of the API.
- No ad hoc queries. A screen that needs data from several resources makes several calls, or the API gains a dedicated route for it.
- The lead API key is described, not declared. The document states the
Authorizationheader ofPOST /public/v1/leadsas a parameter of the operation, not as a security scheme. - The browser part of the careers site is outside the client. Its forms post to endpoints of the careers server, which are not in the OpenAPI document. The careers server then calls the API through the generated client.
Related
Section titled “Related”- ADR-0005: REST with OpenAPI and a generated client.
- API routes: every operation, generated from the document.
- Error handling: the error body and its codes.
- Testing: the tests that keep generated files in sync.