Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VR-P22a.md
T

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

  • 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, staging https://staging-api.hivegrid.de/v1/openapi.json) + Swagger-UI auf API-Host
  • 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 /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