apairon
dcdb6ee637
Befund 1 (Nutzer): Inline-Code war im Dark Mode kaum lesbar.
- src/styles/custom.css: eigene Chip-Farben (--tibi-inline-*), Rahmen, nowrap in der ersten Tabellenspalte
- gemessen: Text/Chip 10,2:1 dunkel, 12,4:1 hell
Befund 2 (beim Nachmessen gefunden): 58 Seiten waren .md - Starlight-Komponenten wurden NICHT gerendert
(rohe <Aside>/<Steps>-Tags, import-Zeile als sichtbarer Text auf 57 Seiten).
- alle 58 Seiten auf .mdx umgestellt und MDX-konform gemacht (Imports, Block-Tags in eigenen Zeilen,
HTML-Kommentare -> {/* */}, geschweifte Klammern escaped)
- nachher: 428 Asides, 87 Steps, 158 Tab-Gruppen gerendert, 0 geleakte Imports
- fehlender Import in reference/hooks-daten ergaenzt
Regressionsschutz: audit-docs.mjs prueft jetzt Komponente-ohne-Import, .md-mit-Komponente,
geleakte Imports und rohe Tags im gebauten dist/. AGENTS.md 3 dokumentiert die .mdx-Regel.
Nebenfund: de.json mit ASCII-Umschreibungen -> Issue tibi-admin-nova #6
Build: 71 Seiten gruen, Audit 7 legitime Platzhalter-Marker
105 lines
5.3 KiB
Plaintext
105 lines
5.3 KiB
Plaintext
---
|
|
title: 'Schnittstellen im Überblick'
|
|
description: 'REST, SSE, MCP, OpenAPI: was wofür gilt und wo die Referenz liegt.'
|
|
---
|
|
|
|
import { TabItem, Tabs } from '@astrojs/starlight/components';
|
|
|
|
Der **tibi-server** spricht vier Sprachen: REST, SSE-Streams, MCP und OpenAPI. Alle hängen unter `/api/v1` (außer `/metrics`). Quelle: `internal/controller/setup.go`.
|
|
|
|
```text title="API-Baum im Überblick"
|
|
/api/v1
|
|
├── System: /login /token/_scopes /llm/* /audit /admin/* /version /mcp
|
|
├── Projekt: /_/:project/:collection … /_/:project/_actions/:action
|
|
│ /_/:project/_/assets/… /_/:project/_/admin/…
|
|
└── Schema: /_openapi/:project
|
|
/metrics (Prometheus, außerhalb)
|
|
```
|
|
|
|
## REST: System gegen Collection
|
|
|
|
<Tabs syncKey="api-sicht">
|
|
<TabItem label="System-Endpunkte">
|
|
|
|
| Methode | Pfad | Wofür |
|
|
|---|---|---|
|
|
| `GET` | `/api/v1/version` | Lebenszeichen (`{"version":"…"}`) |
|
|
| `POST` | `/api/v1/login`, `/api/v1/login/impersonate` | JWT holen / als Admin schlüpfen |
|
|
| `GET` | `/api/v1/token/_scopes` | Gültige PAT-Scopes auflisten |
|
|
| `POST` / `GET` | `/api/v1/llm/chat`, `/api/v1/llm/providers` | Chat (ohne Secrets) / Provider-Namen |
|
|
| `GET` | `/api/v1/audit` | Audit-Logs (`audit.read`) |
|
|
| `GET` / `POST` | `/api/v1/admin/embedding/status`, `/api/v1/admin/shutdown` | Embedding-Status / Stop (`server.shutdown`) |
|
|
|
|
</TabItem>
|
|
<TabItem label="Collection-Endpunkte">
|
|
|
|
| Methode | Pfad | Wofür |
|
|
|---|---|---|
|
|
| `GET` / `POST` | `/_/:project/:collection` | Suchen / anlegen |
|
|
| `GET` | `/_/:project/:collection/_count`, `/_facet`, `/_queue` | Zählen / Facetten / Warteschlange |
|
|
| `GET` / `PUT` / `DELETE` | `/_/:project/:collection/:id` | Lesen / ersetzen / löschen |
|
|
| `PUT` / `DELETE` | `/_/:project/:collection` (ohne ID) | Bulk-Update / Bulk-Delete |
|
|
| `GET` | `/_/:project/:collection/:id/:field`, `…/:field/*path` | Einzelnes Feld / Datei |
|
|
| `GET` / `POST` | `/_/:project/_actions/:action` | Hook-Aktion ohne Collection |
|
|
| `GET` | `/_/:project/_/assets/:name/*path` | Statische Assets |
|
|
|
|
Trick für lange Filter: `POST` mit Header `X-HTTP-Method-Override: GET` — der Body wird zur Query.
|
|
|
|
</TabItem>
|
|
<TabItem label="Projekt-Admin">
|
|
|
|
| Methode | Pfad | Recht |
|
|
|---|---|---|
|
|
| `POST` | `/_/:project/_/admin/reload` | `project.reload` |
|
|
| `POST` / `GET` | `/_/:project/_/admin/regenerate-search`, `…/search-worker/status` | `project.regenerate-search` |
|
|
| `GET` | `/_/:project/_/admin/embedding/status` | Projekt-Admin |
|
|
| `GET` / `POST` / `DELETE` | `/_/:project/_/admin/backup…` | `project.backup` |
|
|
| `GET` / `POST` / `DELETE` | `/_/:project/_/admin/snapshots…` | `project.snapshot` |
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
Antworten sind gzip-komprimiert — außer `.pdf`, `.mp4`, `.jpg`, `.jpeg`, `.png` und dem Pfad `/metrics` —, Body-Limits kaskadieren (Server → Projekt → Collection). Erstellen meldet `201`, Löschen `204` — außer das Projekt will Legacy-Codes.
|
|
|
|
## SSE (Echtzeit und Fortschritt)
|
|
|
|
- Der Realtime-Hub ist ein In-Memory-Pub/Sub **je Projekt**: benannte Kanäle, fester Ringpuffer (Standard 256), Nachhol-Optionen (`LastN`, `MaxAge`, TTL).
|
|
- Volle Kanäle werfen wahlweise Alt oder Neu weg — langsame Leser blockieren nie den Server.
|
|
- **Kein fertiger Abo-Endpunkt:** Der Server liefert keine HTTP-Route für Collection-Abos. Du erreichst den Hub nur über Hooks (`channel.send` / `channel.subscribe`) — typisch als eigene Action (`/_/:project/_actions/:action`), die du selbst als SSE auslieferst.
|
|
- `text/event-stream` liefert der Server fertig nur an zwei Stellen: `POST /api/v1/llm/chat` (Chat-Streaming) und Backup-Analyse-Download (`.../admin/backup/analyze-download`). Snapshot-Streaming ist dagegen Datei-Download mit RAM-Begrenzung, kein SSE.
|
|
- Backup- und Snapshot-Läufe melden Fortschritt als Event-Stream. Bricht der Stream ab, war es das Netzwerk — der Lauf selbst geht weiter.
|
|
|
|
## MCP (KI-Werkzeuge)
|
|
|
|
| Fakt | Wert |
|
|
|---|---|
|
|
| Transport | Streamable-HTTP, JSON-RPC 2.0 |
|
|
| Route | fest `POST` + `GET /api/v1/mcp` — ein gesetztes `mcp.route`/`MCP_ROUTE` wird ignoriert (Routing hart in `setup.go`) |
|
|
| Auth | nur PAT via `X-Auth-Token` — kein JWT, kein Admin-Token |
|
|
| Rechte | jede Prüfung nutzt die gleichen Gates wie REST (nichts kopiert) |
|
|
| Ergebnis-Deckel | `mcp.maxResultItems` (Standard 100) |
|
|
| Admin-Werkzeuge | nur mit `mcp.allowAdminActions: true`, weiter pro Scope begrenzt |
|
|
|
|
```bash title="MCP-Tools auflisten (describe)" {2}
|
|
curl -X POST http://localhost:8080/api/v1/mcp \
|
|
-H "X-Auth-Token: tibi_pat_..." \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
|
|
```
|
|
|
|
## OpenAPI-Generator
|
|
|
|
`GET /api/v1/_openapi/:project` erzeugt die Spezifikation **deines** Projekts frisch aus Config und Collections. Nutze sie für Client-Generierung und als Klick-Referenz. Die Version oben (`/api/v1/version`) sagt dir, ob Server und Spec zusammenpassen.
|
|
|
|
## Welche Referenz wofür
|
|
|
|
| Frage | Antwort liegt in |
|
|
|---|---|
|
|
| Wie heißt Config-Schlüssel X? | [Server-Konfiguration](/server/konfiguration/) |
|
|
| Wer darf Endpunkt Y? | [Sicherheit](/server/sicherheit/) (Tokens, Scopes) |
|
|
| Läuft der Server gesund? | [Betrieb und Beobachtung](/server/betrieb/) (Version, Metriken) |
|
|
| Wie frage ich Daten ab? | Projekt-Seiten ab [Begriffe](/einstieg/begriffe/) |
|
|
| Was ist Tibi überhaupt? | [Was ist Tibi?](/einstieg/was-ist-tibi/) |
|
|
|
|
Verifiziert am 68b4278 2026-10-15 (tibi-server)
|