OpenAPI contract for the DataRaum engine REST surface. The single source of truth for the routes that the Python engine (dataraum-context) publishes and the TanStack Start cockpit (dataraum-cockpit) consumes.
| Path | Purpose |
|---|---|
openapi.yaml |
The current OpenAPI 3.1 spec for /api/* engine routes, generated from FastAPI in dataraum-context |
Future: proto/*.proto |
gRPC protos when the executor split happens (Platform Contract #2) |
That's it. No code. Just spec.
dataraum-context (Python engine + FastAPI)
│
│ CI step: regenerate openapi.yaml from FastAPI app;
│ if diff, open PR / push to dataraum-api main
▼
dataraum-api ◀── single source of truth, versioned via git tags / SHAs
│
│ consumed by:
▼
dataraum-cockpit (TanStack Start)
│
│ build step: openapi-typescript reads openapi.yaml,
│ regenerates src/api/types.ts
▼
typed fetch in TS — no drift between engine and cockpit
The Python side publishes to this repo on diff. The TS side mounts this repo (submodule / pnpm workspace / CI fetch — final mechanism decided at implementation time) and regenerates types at build.
- No "who owns the contract" fight between the Python repo and the TS repo when an end-state Python split happens (
dataraum-engine+dataraum-rest, etc.). Everyone consumes from here. - Symmetric ownership. Neither consumer "owns" the contract; both pull from a third repo.
- Versioning via git tags / SHAs — consumers pin to a specific version, bumps are deliberate.
- Future cross-cutting artifacts (gRPC protos, JSON schemas) have a natural home.
Bootstrapped 2026-05-19. No spec checked in yet — first openapi.yaml lands when DAT-334 ships the first FastAPI route in dataraum-context with a publish-on-diff CI step.
- Cockpit + Engine REST: v1 plan (Confluence) — canonical post-spine plan
- DAT-294 — parent epic
- dataraum/dataraum — engine + FastAPI shell (publisher)
dataraum/dataraum-cockpit— TanStack Start app (consumer; to be created)