87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# Grotti HTTP-API (`/api/v1`)
|
|
|
|
Stand für Android/App-Clients und Integrationen. Nutzer-Anleitungen bleiben unter `docs/Anleitung-*.md`.
|
|
|
|
## Auth
|
|
|
|
| Weg | Header / Cookie | CSRF |
|
|
| --- | --- | --- |
|
|
| Session | Cookie nach `POST /auth/login` | `X-CSRF-Token` bei mutierenden API-Calls |
|
|
| Bearer | `Authorization: Bearer grt_…` | nicht nötig |
|
|
|
|
**Token ausstellen**
|
|
|
|
- Eingeloggt: `POST /tokens` `{name, role?}` → Klartext einmalig in `token`
|
|
- Ohne Session (App): `POST /auth/token` `{username, password, device_name?, role?}` → `201` mit `token` + `user` (Rate-Limit wie Login)
|
|
|
|
Öffentlich ohne Login: `/auth/status`, `/auth/login`, `/auth/token`, `/auth/setup`, `/version`.
|
|
|
|
Rollen: `operator` ≤ `admin`. Admin-only u. a. Benutzer, Backup, volle Einstellungen, Drucker anlegen.
|
|
|
|
**Medien mit Query-Token** (nur GET): `?token=grt_…` für Kamera, Live-Vorschau, Datei-Vorschau (`/dateien/<id>/vorschau`), Projekt-Assets.
|
|
|
|
## Fehler
|
|
|
|
```json
|
|
{"error": "Text", "code": "kurzcode"}
|
|
```
|
|
|
|
HTTP-Status: 400/401/403/404/409/429/503. Bild-Endpunkte liefern bei fehlendem Bild ebenfalls dieses JSON (nicht nur leeren 404).
|
|
|
|
## Pagination
|
|
|
|
Listen akzeptieren `limit` / `offset` wo sinnvoll. Antwort bleibt ein **JSON-Array**; Gesamtzahl im Header `X-Total-Count`.
|
|
|
|
Ohne `limit` liefern `/dateien` und `/spulen` die volle Liste (Web-UI).
|
|
|
|
## Bestätigung
|
|
|
|
Mutierende Druckaktionen brauchen oft `"confirm": true`:
|
|
|
|
- `POST /senden`, `POST /druck-queue`, `POST /ablauf`
|
|
- `POST /projekte/<id>/einreihen`, `POST /auftraege/<id>/einreihen`
|
|
- `POST /drucker/<host>/abraeumen`
|
|
- `steuern` mit `emergency_stop`, `clear_error`, `exclude_object`
|
|
|
|
## Server-Info
|
|
|
|
`GET /version` → `{name, version, api: 1, features: [...]}`.
|
|
|
|
## SSE Live
|
|
|
|
`GET /stream` (Session-Cookie oder Bearer). Events:
|
|
|
|
| Event | Bedeutung |
|
|
| --- | --- |
|
|
| `ping` | Keepalive (~15 s), Payload `{}` |
|
|
| `drucker` | Live-Zustand der Drucker geändert |
|
|
| `queue` | Druckwarteschlange geändert |
|
|
| `senden` | Sende-Auftrag geändert |
|
|
| `ereignis` | Neues Ereignis / Aktivität |
|
|
| `aufgaben` | Offene Aufgaben (Platte …) |
|
|
|
|
Ohne Stream: Client pollt `/drucker?live=1`, `/jetzt`, `/druck-queue`.
|
|
|
|
## Push an Geräte
|
|
|
|
Grotti sendet **kein** FCM. Empfohlen: **ntfy** (Topic unter Einstellungen). Die App kann denselben Topic abonnieren; Secrets (ntfy-Token) bleiben serverseitig.
|
|
|
|
## Wichtige Ressourcen
|
|
|
|
| Bereich | Pfade |
|
|
| --- | --- |
|
|
| Drucker | `GET /drucker?live=1`, `POST /drucker/<host>/pause\|fortsetzen\|abbrechen` (Alias `resume`/`cancel`), `…/steuern`, `…/abraeumen` |
|
|
| Dateien | `GET /dateien?family=&material=&project_id=&host=&q=&limit=&offset=`, Upload multipart, `…/vorschau`, `…/pfad` |
|
|
| Senden / Queue | `POST /senden`, `GET /senden-zuletzt?host=&file_id=`, `GET\|POST /druck-queue?host=&status=`, `POST /ablauf` |
|
|
| Projekte | `GET\|POST /projekte`, `GET /projekte/<id>`, `…/laeufe`, `POST …/einreihen`, Assets |
|
|
| Aufträge | `GET\|POST /auftraege`, Positionen, `…/einreihen` |
|
|
| Material | `GET /spulen?aktiv=1`, Akte, Einlegen |
|
|
| Protokoll | `GET /laeufe`, `GET /laeufe/<id>`, `GET /statistik?project_id=` |
|
|
| Kamera | `GET /kamera?host=`, `…/stream` |
|
|
|
|
Pfadnamen sind überwiegend **deutsch**. Aktionen: deutsch + englische Alias für Pause/Resume/Cancel.
|
|
|
|
## MCP
|
|
|
|
`python -m grotti.mcp_server` nutzt dieselbe REST-API (Teilmenge). Siehe `docs/internal/MCP.md`.
|