Jesko Anschütz aff12a4d81 Doku-Sync: README, TODO, DEVELOPMENT und API-Docs auf Implementierungsstand nachgezogen

README, DEVELOPMENT und TODO spiegelten noch den Stand vor Ebene 1+2 wider.
Checkboxen in TODO von ~18 auf ~70 aktualisiert, drei neue API-Dokumentationsdateien ergänzt.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-23 09:55:36 +01:00

5.3 KiB

Raw Blame History

API Quick Reference

Schnelle Übersicht aller HTTP-Endpoints nach Zweck sortiert.

Agent-Integration

Beim Player-Startup:

POST /api/v1/screens/register

Automatische Selbstregistrierung des Screens im Default-Tenant "morz".

Beim Playlist-Sync (alle ~30s):

GET /api/v1/screens/{screenId}/playlist

Abruf der aktuellen Playlist zum Abspielen.

Status-Reporting (alle ~30s):

POST /api/v1/player/status

Übermittlung des Laufzeitstatus zum Server.

Admin-Dashboard

Übersicht aller Screens:

GET /admin

Web-UI mit Screen-Liste, Status, Provisioning-Formulare.

Screen-Verwaltung:

POST /admin/screens
POST /admin/screens/{screenId}/delete

Provisioning neuer Screens:

POST /admin/screens/provision

Diagnose:

GET /status
GET /status/{screenId}
GET /api/v1/screens/status
GET /api/v1/screens/{screenId}/status

Tenant-Playlist-Management

Manage-UI öffnen:

GET /manage/{screenSlug}

Web-UI für Playlist-Bearbeitung, Uploads, Item-Verwaltung.

Inhalte hinzufügen:

POST /manage/{screenSlug}/upload        (Datei-Upload)
POST /manage/{screenSlug}/items         (Item zur Playlist)
POST /manage/{screenSlug}/media/{mediaId}/delete

Inhalte bearbeiten:

POST /manage/{screenSlug}/items/{itemId}
POST /manage/{screenSlug}/items/{itemId}/delete
POST /manage/{screenSlug}/reorder

Media Management (JSON API)

Media-Assets auflisten:

GET /api/v1/tenants/{tenantSlug}/media

Neue Medien hinzufügen:

POST /api/v1/tenants/{tenantSlug}/media

(Datei-Upload oder externe URL)

Media löschen:

DELETE /api/v1/media/{id}

Playlist Management (JSON API)

Playlist abrufen (Admin):

GET /api/v1/playlists/{screenId}

Playlist abrufen (Player):

GET /api/v1/screens/{screenId}/playlist

(Gibt nur aktive Items zurück)

Items verwalten:

POST   /api/v1/playlists/{playlistId}/items
PATCH  /api/v1/items/{itemId}
DELETE /api/v1/items/{itemId}

Playlist konfigurieren:

PUT   /api/v1/playlists/{playlistId}/order
PATCH /api/v1/playlists/{playlistId}/duration

Screen Management (JSON API)

Self-Registration (Agent):

POST /api/v1/screens/register

Screens eines Tenants auflisten:

GET /api/v1/tenants/{tenantSlug}/screens

Screen erstellen (Admin):

POST /api/v1/tenants/{tenantSlug}/screens

System & Health

Health-Check:

GET /healthz

API-Entrypoint:

GET /api/v1

Metainformationen:

GET /api/v1/meta

Player Local UI (auf dem Gerät)

Player-Seite öffnen:

GET /player

Aktuelle Playlist für lokale Anzeige:

GET /api/now-playing

Systeminformationen anzeigen:

GET /api/sysinfo

Status-Diagnose (Detailed)

Siehe PLAYER-STATUS-HTTP.md für vollständige Dokumentation der Status-Endpoints:

POST   /api/v1/player/status        (Status vom Agent)
GET    /api/v1/screens/status       (Alle Status)
GET    /api/v1/screens/{screenId}/status
DELETE /api/v1/screens/{screenId}/status

Query-Parameter für Filterung:

q — Screen-ID Substring
derived_state — online|degraded|offline
server_connectivity — online|degraded|offline|unknown
stale — true|false
updated_since — RFC3339-Zeitstempel
limit — Anzahl Items

Typische Workflows

1. Neuen Screen provisioning

1. POST /admin/screens (oder /api/v1/tenants/morz/screens)
   → Neuen Screen-Record anlegen

2. POST /admin/screens/provision
   → Provisionierungs-Job starten

3. GET /admin (oder /status)
   → Status überwachen

2. Neue Inhalte hochladen und einbinden

1. POST /manage/{screenSlug}/upload
   → Datei hochladen, Media-Asset erstellen

2. POST /manage/{screenSlug}/items
   → Item zur Playlist hinzufügen (mit media_asset_id)

3. GET /manage/{screenSlug}
   → Playlist-Verwaltung

4. Playlist bearbeiten

1. GET /api/v1/playlists/{screenId}
   → Aktuelle Playlist abrufen

2. PATCH /api/v1/items/{itemId}
   → Dauer, Zeitfenster, Titel ändern

3. PUT /api/v1/playlists/{playlistId}/order
   → Items reordnen

4. GET /api/v1/screens/{screenId}/playlist
   → Player holt neue Version beim Sync ab

5. Status überwachen

1. GET /status (Browser)
   oder
   GET /api/v1/screens/status (JSON)
   → Aktuelle Status aller Screens

2. GET /status/{screenId}
   oder
   GET /api/v1/screens/{screenId}/status
   → Detailstatus für einen Screen

Fehlerbehandlung

HTTP-Status-Codes:

200 — OK (Read erfolgreich)
201 — Created (Ressource erstellt)
204 — No Content (Write erfolgreich, kein Response-Body)
400 — Bad Request (Eingabe-Validierungsfehler)
404 — Not Found (Ressource nicht vorhanden)
500 — Internal Server Error (Server-Fehler)

Alle Fehler folgen dem Modell:

{
  "error": {
    "code": "error_code",
    "message": "Beschreibung",
    "details": null
  }
}

Vollständige Dokumentation

Siehe API-ENDPOINTS.md für:

Detaillierte Request/Response-Beispiele für jeden Endpoint
Query-Parameter und Validierung
Zeitstempel-Formate (RFC3339)
Serverseitige Logik (z.B. Stale-Detection, Derived-State)

5.3 KiB Raw Blame History