# 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** | umgesetzt | ## 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). ## Host-/Surface-Contract (verbindlich) - **Public API nur auf `api.hivegrid.de`** (staging: `staging-api.hivegrid.de`), nicht unter `app.hivegrid.de/api`. - Versionierungs-Prefix ist **`/v1/...`**: `https://api.hivegrid.de/v1/contacts`, `https://api.hivegrid.de/v1/openapi.json`. - Die Web-App (`app.hivegrid.de`) darf API-Links/Docs anzeigen, hostet aber keine Public-API-Routen. - Spätere Modul-Tickets muessen beim Bau bewusst entscheiden: `public_api_surface = none | read | write | webhook` und bei `read/write/webhook` Scope, Serializer, OpenAPI, RLS und Tests ergaenzen. ## Was wir bauen Den **lesenden Teil der versionierten Public-REST-API** (`https://api.hivegrid.de/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** (`https://api.hivegrid.de/v1/openapi.json`) plus Swagger-UI auf dem API-Host. 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.hivegrid.de/v1/openapi.json` · Swagger auf API-Host] | Auto-generierte OpenAPI-3.1-Doku + interaktiver Try-it-out (entwickler-gerichtet) | *(Die REST-Endpoints `https://api.hivegrid.de/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 - [x] `GET https://api.hivegrid.de/v1/{contacts,companies,deals,projects,tasks,leads}` — **cursor-paginiert** + Filter + Sort + **Sparse-Fieldsets** + Embed (Tiefe 1) - [x] `read_only`-Scope **blendet sensible Felder aus** (Feld weglassen, **nicht 403**) - [x] **OpenAPI-3.1 auto-generiert** (`https://api.hivegrid.de/v1/openapi.json`, staging `https://staging-api.hivegrid.de/v1/openapi.json`) + Swagger-UI auf API-Host - [x] Antworten respektieren **RLS** (`app.tenant_id` pro Transaktion gesetzt) — kein Cross-Tenant-Leck - [x] Konnektor `tenantHasModule('public_api')` gated die API-Verfügbarkeit (Tarif-Gate-Vollausbau in VR-P22b) - [x] Versionierungs-Präfix `/v1/` auf `api.hivegrid.de` etabliert (Breaking-Changes → `/v2/`); keine Public-API unter `app.hivegrid.de/api` ## Umsetzung 2026-07-03 **Stand:** 6/6 DoD = 100 % done. **Proof:** `pnpm typecheck` grün; `pnpm lint` grün; `pnpm test` grün (572 Test-Dateien passed, 8 skipped; 3639 Tests passed, 46 skipped); `pnpm run verify:api-inventory` grün (17 Tests); `pnpm --filter @hivegrid/api typecheck` grün; `pnpm exec vitest run apps/api/src/public-api/resources.test.ts apps/api/src/app.test.ts apps/api/src/openapi.test.ts apps/api/src/route-access-inventory.test.ts` grün (140 Tests); `git grep -nE "@ai-sdk/openai[^-]|@ai-sdk/anthropic|remix-auth-google" -- "*.ts"` leer. **Umgesetzt:** - Neue Public-API-Resource-Registry + Read-Service unter `apps/api/src/public-api/`. - Routen `GET /v1/contacts`, `/v1/companies`, `/v1/deals`, `/v1/projects`, `/v1/tasks`, `/v1/leads` unter `api.hivegrid.de`-Runtime registriert, nicht in der Web-App. - API-Key-Validierung, API-Key-Log, IP-Log, Tarif-/Modul-Gate über den vorhandenen Entitlement-Key `api`, Cursor-Pagination, Filter, Sort, Sparse-Fieldsets und Embed Tiefe 1. - RLS pro Read-Transaktion via `set_config('app.tenant_id', tenantId, true)`. - OpenAPI-3.1-Pfade werden aus der Registry generiert und in `/v1/openapi.json` eingebunden. - `/v1/docs` ist ein self-contained Swagger-style OpenAPI-Explorer mit Try-request-Funktion. - Route-Access-Inventar + OpenAPI-Security-Tests für alle neuen Routen nachgezogen. **Hinweis:** Die Ticket-Doc nennt `tenantHasModule('public_api')`; im aktuellen Entitlements-Modell ist der bestehende Feature-/Modul-Key fuer Public-API `api` (`packages/entitlements`). Die Runtime gate't daher bewusst gegen `api`; ein separater Scope-/Rate-Limit-/Webhook-Vollausbau bleibt VR-P22b. ## 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. - **API-Extension-Pattern fuer Folgemodule:** Jedes neue Modul dokumentiert `public_api_surface = none | read | write | webhook`. Wenn exponiert wird: Resource-Pfad unter `api.hivegrid.de/v1`, Scope(s), Serializer/Redaction, RLS/Tenant-Scope, OpenAPI-Schema, Rate-Limit/Usage-Logging und Tests sind Pflicht. ## Quellen (granular) - `ROADMAP-V2.md` → §v2-P1 (Success-Criteria 1/4, Screens) — **Hauptquelle** - `ROADMAP.md` → Phase 22 - Historische Milestone-Zuordnung: 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) ## Dev-Nachzug (nach Davids `D-P22`-Delta) - [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst - [ ] REQUIREMENTS/ROADMAP nachgezogen - [ ] Plane-Ticket `VR-P22a` aktualisiert