Skip to content

OpenAPI contract

The Console API is described by an OpenAPI 3 document generated from the routes themselves, so it cannot describe a route that does not exist or miss one that does.

  • A deployment serves it at GET /api/v1/openapi.yaml and GET /api/v1/openapi.json (any logged-in role or API token).
  • The repository holds a copy at console/api/openapi.yaml. just console-openapi rewrites it; the unit tests, which CI runs, fail when the file differs from what the routes generate and check every real response against its schema.
  • The Console's TypeScript types are generated from it (just console-types, checked by just console-types-check).
  • The route reference and agents pages are generated from the same document, so they follow it.

What it carries

Every route has a summary that ends with the role that may call it ((admin), (operator); none for a viewer) and an x-kapelle-role extension with the same value, a tag (the area) and its request and response schemas. Errors are application/problem+json. A write of an existing resource documents its If-Match header; lists document limit and cursor.

Using it

Hand GET /api/v1/openapi.yaml to a client generator or to an agent as the contract. For conventions the document does not express (roles, If-Match, safety rules, the common tasks in order), read Managing Kapelle through its API and the Console API page.

Changing it

A route is added in the app and described in services/controller/src/kapelle_controller/console/openapi.py (ROUTE_DOCS, SCHEMAS); then just console-openapi and just console-types regenerate the checked-in files, and the same commit holds all three.