Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/VR-P22a.md
T

4.3 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 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