2.5 KiB
Core-API-Referenz für Module
(Quelle: docs/core/core-api-implementation-plan.md §3a/§9, docs/core/hubrobotix-manifest.md
Gesetz 1/2, interne Server-Details entfernt)
Grundprinzip
Dein Modul-Code hält nie ein Datenbank-Passwort — auch nicht für dein eigenes Schema. Jeder
Datenzugriff läuft über HTTP-Aufrufe gegen die Core-API, authentifiziert mit einem
pro-Modul-scoped Token (Authorization: Bearer <token> + X-Module-Key: <dein_module_key>).
Zwei Endpunkt-Familien
1. mod/data/* — deine eigenen Tabellen
Eine generische, auf dein eigenes Schema (mod_<dein_key>) beschränkte Endpunkt-Familie für
CRUD auf deinen eigenen Tabellen. Dein Token kann ausschließlich auf mod_<dein_key>.* zugreifen —
selbst ein Bug in deinem Code kann nie eine fremde Tabelle erreichen (das ist keine reine
Anwendungslogik-Prüfung, sondern serverseitig auf Datenbank-Rollen-Ebene erzwungen).
2. Freigegebene Querschnittsdienste
Für Funktionen, die dein Modul braucht, die aber Core-Daten betreffen (kein eigenes Schema):
| Endpunkt | Zweck |
|---|---|
auth/verify |
JWT-Verifikation eines eingeloggten Nutzers |
llm/complete |
KI-Vervollständigung (Anthropic/OpenAI/Ollama je nach Mandanten-Konfiguration) |
prompt/get |
Lädt einen deklarierten Prompt-Text (System-Standard oder Mandanten-Override) |
authz/check |
Prüft Modul-Freischaltung + Nutzerrechte für den aktuellen Request |
template/render |
Rendert ein E-Mail-Template mit Platzhaltern |
email/send |
Versendet eine E-Mail über den zentralen SMTP-Dienst |
log/write |
Schreibt einen strukturierten Log-Eintrag |
Wichtig: Für komplexere eigene Server-Logik (Joins, Transaktionen über mehrere eigene Tabellen,
eigene Business-Regeln) gibt es keinen bespoken Custom-Endpunkt in der Core-API — diese Logik
gehört in deinen eigenen Workflow/Dienst, der mehrere mod/data/*-Aufrufe kombiniert.
Fehlerbehandlung
Jede Antwort mit HTTP-Status ≥ 400 enthält { "error": "<Nachricht>" }. Statuscode 5xx zeigt einen
internen Fehler an unsererseits (dein Modul sollte das nicht als Nutzerfehler behandeln), 4xx zeigt
einen Fehler auf deiner Seite (falscher Scope, ungültige Parameter etc.).
Contract-Versionierung
Die Core-API-Endpunkte stehen unter /v1/.... Dein manifest.json deklariert "api_contract": "v1"
— ein zukünftiger /v2-Bruch wird rechtzeitig angekündigt und betrifft dich nur, wenn du selbst auf
v2 migrierst.
Weiter mit 03-security-rules.md.