# VR-P22a · Public-API: OpenAPI + Read-Endpoints (M161) | | | |---|---| | **Typ** | Dev (Code) | | **Owner** | Raffael | | **Phase** | Phase 22 (v2-P1) — Public-API & Webhooks | | **Cycle/Fenster** | v2-W1 — Public-API/Postfach/Abo/KI-Start · fällig 2026-07-15 | | **Status** | geplant | ## Abhängigkeiten & Parallelität - **Blocked by:** `R-P2b` (v1-`ApiKey`-Modell — lag aus v1/M027 ungenutzt bereit, wird hier erstmals genutzt; RLS via `app.tenant_id`) - **Blocks:** `VR-P22b` (Auth/Scopes/Rate-Limit + Webhooks bauen auf der Read-API auf) - **Läuft parallel zu:** `VA-P23` (Postfach-Sync, Akeshan) — teilen sich später die **Webhook-Ingest-Infra** (in VR-P22b), hier aber kein Schema-Konflikt: Read-API ist rein lesend über bestehende Entitäten. Eigene `prisma/schema/publicApi.prisma` (AD-21) für API-eigene Tabellen, fremde Domänen nur lesend berührt. - **Konflikt-Risiko:** keines (Read-only). ## Was wir bauen Den **lesenden Teil der versionierten Public-REST-API** (`/api/v1/…`): externe Systeme lesen die HiveGrid-Hauptentitäten **Kontakte, Firmen/Organisationen, Deals, Projekte, Tasks, Leads** cursor-paginiert, mit Filter/Sort/Sparse-Fieldsets/Embed (Tiefe 1). Dazu eine **auto-generierte OpenAPI-3.1-Spezifikation** (`/api/v1/openapi.json`) plus Swagger-UI. Bewusster Recut: **Read-only**, kein Voll-CRUD, kein GraphQL, kein 3-Legged-OAuth (alles später). Auth/Scopes/Rate-Limit folgen in VR-P22b — diese Teilphase liefert die Endpoint-Struktur, Serialisierung und Doku-Generierung. ## Benötigte Screens (Backend bedient — Design liefert `D-P22`) | Screen [Route] | Kern-Inhalt | |---|---| | OpenAPI/Swagger-UI [`/api/v1/openapi` · Swagger] | Auto-generierte OpenAPI-3.1-Doku + interaktiver Try-it-out (entwickler-gerichtet) | *(Die REST-Endpoints `/api/v1/contacts\|companies\|deals\|projects\|tasks\|leads` sind serverseitig — kein eigener Screen außer Swagger-UI. API-Key-Verwaltungs-Screens liegen in VR-P22b.)* ## Definition of Done - [ ] `GET /api/v1/{contacts,companies,deals,projects,tasks,leads}` — **cursor-paginiert** + Filter + Sort + **Sparse-Fieldsets** + Embed (Tiefe 1) - [ ] `read_only`-Scope **blendet sensible Felder aus** (Feld weglassen, **nicht 403**) - [ ] **OpenAPI-3.1 auto-generiert** (`/api/v1/openapi.json`) + Swagger-UI - [ ] Antworten respektieren **RLS** (`app.tenant_id` pro Transaktion gesetzt) — kein Cross-Tenant-Leck - [ ] Konnektor `tenantHasModule('public_api')` gated die API-Verfügbarkeit (Tarif-Gate-Vollausbau in VR-P22b) - [ ] Versionierungs-Präfix `/api/v1/` etabliert (Breaking-Changes → `/api/v2/`) ## Technische Bausteine - **Entities** (eigene `prisma/schema/publicApi.prisma`, AD-21): `ApiKey` ([v2]-markiert im ENTITY-MODEL: `key_hash`, `scope`, `expires_at`, [RLS][Soft-Delete]) — in dieser Teilphase nur **lesend referenziert** (Scope-Filter), Auth-Logik kommt in VR-P22b. Lesende Entitäten (`Kontakt`, `Projekt`/Pipeline-Views „deals"/„projects", `Task`, Lead) werden über ihre Domänen-Schemata gelesen, **nicht** verändert. - **RLS:** jede Query in einer Transaktion mit `SET LOCAL app.tenant_id` — der API-Key bestimmt den Tenant. - **Konnektor:** `tenantHasModule('public_api')` (Sidebar/Routes/API gated, AD-Konnektor-Pflicht). - **`is_demo_data`:** nicht relevant (kein Seeding eigener Daten), aber Read-API muss `is_demo_data`-Datensätze normal ausliefern (Demo-Tenant-tauglich). - **Serialisierung:** Sparse-Fieldsets + Embed-Resolver (Tiefe 1) als Query-Layer; `read_only`-Scope filtert sensible Felder serverseitig vor der Serialisierung. - **OpenAPI-Tooling:** vor Bau wählen (z.B. zod-to-openapi für 3.1) — Spec aus den Endpoint-Schemata generieren, nicht manuell pflegen. ## Quellen (granular) - `ROADMAP-V2.md` → §v2-P1 (Success-Criteria 1/4, Screens) — **Hauptquelle** - `ROADMAP.md` → Phase 22 - `PHASE-SOURCES.md` → Phase 22 (M161, M162, M163, M027; M027 = aus v1-Scope-Schnitt 12.06. mit Public-API gebündelt) - `ENTITY-MODEL.md` → `ApiKey` [v2] (key_hash/scope/expires_at) + Domäne 5 (CRM-Kern als Read-Quelle) - `designer-briefs/P22-public-api-webhooks.md` (Swagger-UI-Screen, Recut-Hinweis) - `_bmad-output/specs/M34-public-api.md` (Read-API-Teil) ## Dev-Nachzug (nach Davids `D-P22`-Delta) - [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst - [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen - [ ] Plane-Ticket `VR-P22a` aktualisiert