The API is described by a generated OpenAPI document #2028

Closed
opened 2026-11-16 08:12:16 +00:00 by sam · 1 comment
Owner

The binary's HTTP API is hand-registered per module, and the dashboard copies its JSON shapes by hand (ui/src/archie/api.ts), so nothing catches drift between them and no other frontend can be built against a published contract.

Describe the API with an OpenAPI 3.1 document generated from the handlers:

  • Huma on the standard library mux (humago) is the candidate: each operation is registered with typed input and output, and the document follows from them. Before adopting it, confirm its JSON layer can sit on encoding/json/v2.
  • Core serves the document at /api/openapi.json, versioned with the release. The committed copy is checked for staleness in task check, like proto and sqlc output.
  • Schemas carry what a generic frontend needs to render them: titles, descriptions, enums, write-only for secrets, and tags that group operations by module.
  • The default dashboard renders from the document at runtime (#2029). The UI package generates its typed client from it (#2030).

Done when: every /api route appears in the served document with its request and response schemas, and a frontend built from the document alone can sign in and list runs.

The binary's HTTP API is hand-registered per module, and the dashboard copies its JSON shapes by hand (`ui/src/archie/api.ts`), so nothing catches drift between them and no other frontend can be built against a published contract. Describe the API with an OpenAPI 3.1 document generated from the handlers: - Huma on the standard library mux (`humago`) is the candidate: each operation is registered with typed input and output, and the document follows from them. Before adopting it, confirm its JSON layer can sit on `encoding/json/v2`. - Core serves the document at `/api/openapi.json`, versioned with the release. The committed copy is checked for staleness in `task check`, like proto and sqlc output. - Schemas carry what a generic frontend needs to render them: titles, descriptions, enums, write-only for secrets, and tags that group operations by module. - The default dashboard renders from the document at runtime (#2029). The UI package generates its typed client from it (#2030). Done when: every `/api` route appears in the served document with its request and response schemas, and a frontend built from the document alone can sign in and list runs.
sam added the featurehigh labels 2026-11-16 08:12:16 +00:00
sam added a new dependency 2026-11-16 08:12:25 +00:00
sam added a new dependency 2026-11-16 08:12:27 +00:00
sam changed title from The API is described by a generated OpenAPI document, and the dashboard's client is generated from it to The API is described by a generated OpenAPI document 2026-11-16 08:26:24 +00:00
Author
Owner

Done in 1026d5e3b. All 52 /api operations are registered with Huma behind one admin-token middleware. The document is served at /api/openapi.json and .yaml, with a docs page at /api/docs, and committed as api/openapi.yaml. archie openapi prints it with no database, and task check rejects a stale copy. Webhook intake stays outside the API so each source verifies its token before the body is read.

Changes on the wire: errors are RFC 9457 problem details (the Vue client reads detail), and an invalid body answers 422 naming each bad field. Encoding with json/v2 is left to #2031. The docs page loads its viewer from a CDN, which the generated dashboard (#2029) should not copy.

Verified against a local binary: no token gets 401; every list route answers 200; a settings read written back is accepted; people and triggers save with optional fields omitted. The admin-token test now runs against the real API and fails when the check is disabled.

Done in 1026d5e3b. All 52 `/api` operations are registered with Huma behind one admin-token middleware. The document is served at `/api/openapi.json` and `.yaml`, with a docs page at `/api/docs`, and committed as `api/openapi.yaml`. `archie openapi` prints it with no database, and `task check` rejects a stale copy. Webhook intake stays outside the API so each source verifies its token before the body is read. Changes on the wire: errors are RFC 9457 problem details (the Vue client reads `detail`), and an invalid body answers 422 naming each bad field. Encoding with json/v2 is left to #2031. The docs page loads its viewer from a CDN, which the generated dashboard (#2029) should not copy. Verified against a local binary: no token gets 401; every list route answers 200; a settings read written back is accepted; people and triggers save with optional fields omitted. The admin-token test now runs against the real API and fails when the check is disabled.
sam closed this issue 2026-11-16 09:05:24 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#2028