124 lines
4.6 KiB
Markdown
124 lines
4.6 KiB
Markdown
# REST-API
|
||
|
||
Alle Funktionen des Web-UI sind auch per REST-API verfügbar. Basis-URL: `http://<host>:8484`
|
||
|
||
Die interaktive API-Dokumentation (Swagger-UI unter `/docs`) ist standardmäßig deaktiviert und kann mit der Umgebungsvariable `ENABLE_API_DOCS=1` eingeschaltet werden.
|
||
|
||
## Endpunkte
|
||
|
||
### System
|
||
|
||
| Methode | Pfad | Beschreibung |
|
||
|---------|------|-------------|
|
||
| `GET` | `/api/health` | Health Check (kein Auth nötig) |
|
||
| `GET` | `/api/config` | Konfiguration lesen (ohne Secrets) |
|
||
| `PUT` | `/api/config` | Konfiguration speichern (siehe [Konfiguration](#konfiguration)) |
|
||
|
||
### Jobs
|
||
|
||
| Methode | Pfad | Beschreibung |
|
||
|---------|------|-------------|
|
||
| `GET` | `/api/jobs` | Alle Jobs auflisten |
|
||
| `POST` | `/api/jobs` | Neuen Job erstellen |
|
||
| `GET` | `/api/jobs/:id` | Job-Details abrufen |
|
||
| `PUT` | `/api/jobs/:id` | Job aktualisieren |
|
||
| `DELETE` | `/api/jobs/:id` | Job löschen (nicht während einer laufenden Aufnahme → 400) |
|
||
| `POST` | `/api/jobs/:id/record` | Job-Aufnahme starten (läuft bereits → 409) |
|
||
|
||
### Senderbibliothek
|
||
|
||
| Methode | Pfad | Beschreibung |
|
||
|---------|------|-------------|
|
||
| `GET` | `/api/stations` | Alle gespeicherten Sender auflisten |
|
||
| `POST` | `/api/stations` | Neuen Sender erstellen |
|
||
| `GET` | `/api/stations/:id` | Sender-Details abrufen |
|
||
| `PUT` | `/api/stations/:id` | Sender aktualisieren |
|
||
| `DELETE` | `/api/stations/:id` | Sender löschen (verknüpfte Jobs werden gelöst) |
|
||
|
||
### Schnellaufnahme
|
||
|
||
| Methode | Pfad | Beschreibung |
|
||
|---------|------|-------------|
|
||
| `POST` | `/api/quick-record` | Schnellaufnahme starten |
|
||
|
||
```json
|
||
{
|
||
"url": "rtmp://example.com/live/stream",
|
||
"name": "Meine Aufnahme",
|
||
"stream_type": "auto",
|
||
"max_duration": 3600
|
||
}
|
||
```
|
||
|
||
Erlaubte URL-Schemata: `http`, `https`, `rtmp`, `rtmps`, `rtsp`, `rtsps`. Für Job-Felder gelten dieselben Prüfungen wie im Web-UI (siehe [Jobs](jobs.md#validierung)).
|
||
|
||
### Aufnahmen
|
||
|
||
| Methode | Pfad | Beschreibung |
|
||
|---------|------|-------------|
|
||
| `GET` | `/api/recordings` | Alle Aufnahmen (Parameter: `active_only`, `limit`) |
|
||
| `GET` | `/api/recordings/:id` | Aufnahme-Status |
|
||
| `POST` | `/api/recordings/:id/stop` | Aufnahme stoppen |
|
||
| `POST` | `/api/recordings/:id/extend?minutes=30` | Aufnahme verlängern (`minutes` 1–1440; bei unbegrenzter Aufnahme → 400) |
|
||
| `POST` | `/api/recordings/:id/unlimited` | Zeitlimit entfernen |
|
||
|
||
### Logs
|
||
|
||
| Methode | Pfad | Beschreibung |
|
||
|---------|------|-------------|
|
||
| `GET` | `/api/logs` | Protokoll (Parameter: `limit`, `level`) |
|
||
|
||
Zeitstempel in API-Antworten sind UTC mit Offset, z.B. `2026-10-11T14:30:00+00:00`.
|
||
|
||
## Konfiguration
|
||
|
||
`GET /api/config` liefert keine Secrets. Stattdessen zeigen boolesche Felder an, ob ein Wert gesetzt ist:
|
||
|
||
| Feld | Bedeutung |
|
||
|------|-----------|
|
||
| `auth.password_set` | Passwort ist gesetzt |
|
||
| `ntfy.token_set` | NTFY-Token ist gesetzt |
|
||
| `plik.api_key_set` | Plik-API-Key ist gesetzt |
|
||
|
||
Regeln für `PUT /api/config`:
|
||
|
||
- Secret-Felder (`auth.password`, `ntfy.token`, `plik.api_key`) weglassen = unverändert
|
||
- Leerer String `""` = Secret entfernen (nicht beim Passwort)
|
||
- `auth.enabled: true` erfordert ein Passwort (mind. 8 Zeichen)
|
||
- `download_path` muss innerhalb von `RECORDING_ROOTS` liegen
|
||
- Unbekannte Schlüssel → 422
|
||
- Der Abschnitt `server` kann nicht über die API geändert werden
|
||
|
||
```bash
|
||
curl -u admin:passwort -X PUT http://localhost:8484/api/config -H "Content-Type: application/json" -d '{"ntfy": {"url": "https://ntfy.sh/mein-topic", "events": "start,error"}}'
|
||
```
|
||
|
||
## Authentifizierung
|
||
|
||
Bei aktiviertem Auth (Standard bei Neuinstallationen) wird Basic Authentication verwendet:
|
||
|
||
```bash
|
||
curl -u admin:passwort http://localhost:8484/api/jobs
|
||
```
|
||
|
||
- Der Health-Endpunkt (`/api/health`) ist immer ohne Auth erreichbar.
|
||
- Nach 10 fehlgeschlagenen Logins innerhalb von 5 Minuten antwortet der Server für diese IP bis zum Ende des Zeitfensters mit 429.
|
||
|
||
## Browser-Zugriff
|
||
|
||
CORS ist nicht aktiviert. Schreibende Requests (`POST`, `PUT`, `DELETE`) mit fremdem `Origin` werden mit 403 abgewiesen. Die API ist damit aus Skripten/curl (ohne `Origin`-Header) und aus dem eigenen Web-UI nutzbar, nicht aber von fremden Webseiten.
|
||
|
||
## Fehlercodes
|
||
|
||
Fehler werden als JSON mit Feld `detail` zurückgegeben.
|
||
|
||
| Code | Bedeutung |
|
||
|------|-----------|
|
||
| `400` | Ungültige Anfrage, Meldung auf Deutsch (z.B. nicht erlaubte ffmpeg-Argumente, unzulässiger Pfad) |
|
||
| `401` | Anmeldung erforderlich oder fehlgeschlagen |
|
||
| `403` | Cross-Site-Request abgewiesen |
|
||
| `404` | Objekt nicht gefunden |
|
||
| `409` | Konflikt, z.B. Job nimmt bereits auf |
|
||
| `422` | Validierungsfehler (ungültige Felder, unbekannte Schlüssel) |
|
||
| `429` | Zu viele fehlgeschlagene Logins |
|