0104. A typed API client from an OpenAPI description
- Status: Accepted (Mik, 16 Nov 2026)
- Date: 2026-11-15
- Decided by: domain E implementer (internal only)
- Planning item: WP8, D31
Context
api(url).get<Post[]>("/posts") trusts the page: a misspelt path, a missing parameter or a wrong answer type is found only when the app runs against the server. Most servers already publish an OpenAPI description.
Decision
duolith api generate <name>.openapi.yaml(or.json) writes<name>.tsbeside it: a type for each named schema and an interface<Name>Apiof every path, each with its operations by method and each operation'sparams,query,bodyandresponseas types. Every build andduolith devdoes the same for each description in the project'sapi/folder, before the type check, writing the file only when it changed.- Pages import it with
import type(a project's.tsfile can only be imported as types, decision 0095) and calltypedApi<PostsApi>(url)from@duolith/client:server.get("/posts", { query: { page: 2 } }),server.post("/posts/{id}/like", { params: { id } }). A path the description does not have for that method, a parameter of the wrong type, or a missing body is a type error (E0340), and fails the build. typedApisends throughapi(), so the errors (ApiError), headers, idempotency keys, retries and abort signals are the same.- A description Duolith cannot read is E0516; a schema it cannot type (a
$refto another file, an unknown type) is E0517.
Alternatives considered
| Option | Why not |
|---|---|
| A generated runtime client (functions per operation) | Ships code per operation, and a second way to call a server beside api() |
| openapi-typescript as a dependency | A Node dependency in every build, and its output is not shaped for typedApi |
| Check calls in the analyzer | A second type checker; TypeScript already checks the script view |
Consequences
The generated file holds only types, so nothing of it ships. Operation ids are not used: a call names the path as the description writes it.