Duolith docs

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>.ts beside it: a type for each named schema and an interface <Name>Api of every path, each with its operations by method and each operation's params, query, body and response as types. Every build and duolith dev does the same for each description in the project's api/ folder, before the type check, writing the file only when it changed.
  • Pages import it with import type (a project's .ts file can only be imported as types, decision 0095) and call typedApi<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.
  • typedApi sends through api(), 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 $ref to another file, an unknown type) is E0517.

Alternatives considered

OptionWhy 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 dependencyA Node dependency in every build, and its output is not shaped for typedApi
Check calls in the analyzerA 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.