52 lines
2.5 KiB
Markdown
52 lines
2.5 KiB
Markdown
# 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](03-security-rules.md).
|