7.1 KiB
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 viaapp.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. Eigeneprisma/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 unterapp.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 | webhookund beiread/write/webhookScope, 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
GET https://api.hivegrid.de/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 (
https://api.hivegrid.de/v1/openapi.json, staginghttps://staging-api.hivegrid.de/v1/openapi.json) + Swagger-UI auf API-Host - Antworten respektieren RLS (
app.tenant_idpro Transaktion gesetzt) — kein Cross-Tenant-Leck - Konnektor
tenantHasModule('public_api')gated die API-Verfügbarkeit (Tarif-Gate-Vollausbau in VR-P22b) - Versionierungs-Präfix
/v1/aufapi.hivegrid.deetabliert (Breaking-Changes →/v2/); keine Public-API unterapp.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/leadsunterapi.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.jsoneingebunden. /v1/docsist 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 mussis_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 unterapi.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) — HauptquelleROADMAP.md→ Phase 22PHASE-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-P22aaktualisiert