SPB Git

Repository Public

README.md 3.7 KB

# api-contracts

openapi.yaml is the single contract (OpenAPI 3.1.0) of the public API served by control-api under /api/v1 (https://clustr.spboucher.ai/api/v1). Together with the SQL migrations it is the source of truth (see docs/DESIGN-BRIEF.md). The agent protocol (/agent/v1, mTLS) is not part of this document.

# Consumers

Target Generator Notes
Go server (services/) oapi-codegen v2, strict server no skip-prune needed: every schema is referenced
Web (apps/web) openapi-typescript + openapi-fetch baseUrl: "/api/v1"
Apple (packages/swift-core, MCCCore) swift-openapi-generator shared by macOS and iOS

Change the contract first, regenerate, then implement. Never edit generated code.

# Validate

sh
npx --yes @redocly/cli@latest lint packages/api-contracts/openapi.yaml
npx --yes openapi-typescript@latest packages/api-contracts/openapi.yaml -o /tmp/mcc-openapi-check.d.ts

Lint must report no error. Five warnings are accepted: the localhost development server, three unauthenticated Meta operations without a 4xx response, and /agents/enrollment-tokens/{id} vs /agents/{id}/revoke (different methods, static segment wins).

# Conventions

  • Operations: unique camelCase operationId, exactly one tag, x-permission on every operation (authenticated = any session, none = no session), x-step-up: true when a passkey ceremony younger than 5 minutes is required. POST /actions is the exception: permission and step-up depend on the action type (x-permission-note, x-step-up-note).
  • Schemas: all named under components/schemas; no oneOf / anyOf / allOf; optional fields are omitted, never null; details are composed (NodeDetail { node, ... }, AlertDetail { alert, timeline }) instead of inherited; free-form JSON (additionalProperties: true) only for WebAuthn payloads, JSON Schemas, params, results, meta, widget config and error details.
  • Types: ids uuid; timestamps date-time in UTC; byte counts int64; enums are string enums.
  • Security: cookieSession (__Host-mcc_session) or bearer. Cookie sessions must send X-MCC-CSRF on every non-safe method (declared optional in the schema because bearer sessions do not use it). The invitation setup transaction uses setupCookie (__Host-mcc_setup) or setupHeader (X-MCC-Setup-Transaction).
  • Errors: every non-2xx is ErrorResponse { error: { code, message, details?, correlation_id } }, through the reusable responses BadRequest, Unauthenticated, Forbidden, NotFound, Conflict, Gone, Unprocessable, RateLimited (Retry-After), Unavailable. The code table is in info.description; code is an open string, clients must tolerate unknown values. 500 internal can be returned by any operation and is not repeated.
  • Correlation: every response carries X-Correlation-Id.
  • Pagination: limit (1-200, default 50) + cursor; responses are { items, next_cursor? }.
  • Telemetry: Freshness = fresh | stale | offline; Availability = available | unavailable | unsupported | permission_denied | stale | offline. Telemetry-derived resources carry observed_at and freshness. A value that cannot be measured is absent, never zero.
  • Series: points are [ts_ms, avg, min, max] arrays (MetricPoints).
  • Idempotency: Idempotency-Key is required on POST /actions and POST /jobs; a replay answers 200 with the original resource, a new request 201.
  • Events: GET /events is text/event-stream. Payload schemas are NodeStateEvent, AlertChangedEvent, ... EventStreamFrame / EventPayloads only exist so that generators emit every payload type; on the wire data is directly the payload of the topic.
Files main
Menu

Theme