4.3 KiB
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 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).
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_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
/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 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.
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