API

Ilavrita describes its HTTP surface two ways, and they answer different questions.

A FHIR client should trust the CapabilityStatement. It is generated by the running server, so it cannot describe a build other than the one answering the request. The OpenAPI description is for tooling, code generation and human reference.

Reading the reference

make api-docs   # renders docs/api.html

CI renders the same file on every push and attaches it as the api-reference artefact. It is not committed, because a generated file in version control invites edits that the next build silently discards.

Keeping it honest

Two checks run in .github/workflows/api.yml:

make api-lint     # the description is a valid OpenAPI 3.1 document
make api-verify   # the description matches a running server

api-verify boots the server and requests every documented route, comparing status, content type and top-level response fields. A description that has drifted is worse than none — callers trust it and are wrong — so drift fails the build rather than raising a warning.

Routes are added to the description as behaviour ships. It should never describe something the server cannot do.

Lint configuration

redocly.yaml disables operation-2xx-response and operation-4xx-response. Both would require declaring responses that do not exist: /healthz cannot return a 4XX, and the FHIR catch-all returns 501 for everything. Accuracy beats uniform shape.

Generated clients

The TypeScript SDK does not generate its types from this description yet. openapi-typescript drives the TypeScript compiler API, which the native TypeScript 7 compiler this repository uses does not expose, so generation fails. The SDK's types are small and hand-written for now; revisit when the generator supports TypeScript 7.