Changing the REST API

Core’s REST API has an explicit contract: core/api/openapi.yaml. The server, its tests and the web client are all checked against it.

How the contract is enforced

  • Route coverage: httpapi.Register returns every route it registers; a test fails unless that set equals the operations in the spec.

  • Response and request validation: every REST test in core/internal/transport/httpapi runs through a middleware (kin-openapi) that validates each response, and each request the server accepted, against the spec. Schemas use additionalProperties: false, so an undocumented field fails the tests.

  • Generated client: web/src/lib/api/schema.d.ts is generated from the spec (openapi-typescript) and used through openapi-fetch (web/src/lib/api/client.ts). make api-check (part of make web-check and CI) fails when it is stale.

Workflow

  1. Change core/api/openapi.yaml together with the handler.

  2. Cover the new behaviour in the REST tests (they validate against the spec automatically).

  3. make api-generate and commit web/src/lib/api/schema.d.ts.

  4. Update REST API when the change affects users.

  5. make check.

In YAML flow mappings ({ … }), quote descriptions that contain commas.