morz-infoboard/docs/API-QUICK-REFERENCE.md

# API Quick Reference

Schnelle Übersicht aller HTTP-Endpoints nach Zweck sortiert.

---

## Agent-Integration

**Beim Player-Startup:**
```http
POST /api/v1/screens/register
```
Automatische Selbstregistrierung des Screens im Default-Tenant "morz".

**Beim Playlist-Sync (alle ~30s):**
```http
GET /api/v1/screens/{screenId}/playlist
```
Abruf der aktuellen Playlist zum Abspielen.

**Status-Reporting (alle ~30s):**
```http
POST /api/v1/player/status
```
Übermittlung des Laufzeitstatus zum Server.

---

## Admin-Dashboard

**Übersicht aller Screens:**
```http
GET /admin
```
Web-UI mit Screen-Liste, Status, Provisioning-Formulare.

**Screen-Verwaltung:**
```http
POST /admin/screens
POST /admin/screens/{screenId}/delete
```

**Provisioning neuer Screens:**
```http
POST /admin/screens/provision
```

**Diagnose:**
```http
GET /status
GET /status/{screenId}
GET /api/v1/screens/status
GET /api/v1/screens/{screenId}/status
```

---

## Tenant-Playlist-Management

**Manage-UI öffnen:**
```http
GET /manage/{screenSlug}
```
Web-UI für Playlist-Bearbeitung, Uploads, Item-Verwaltung.

**Inhalte hinzufügen:**
```http
POST /manage/{screenSlug}/upload        (Datei-Upload)
POST /manage/{screenSlug}/items         (Item zur Playlist)
POST /manage/{screenSlug}/media/{mediaId}/delete
```

**Inhalte bearbeiten:**
```http
POST /manage/{screenSlug}/items/{itemId}
POST /manage/{screenSlug}/items/{itemId}/delete
POST /manage/{screenSlug}/reorder
```

---

## Media Management (JSON API)

**Media-Assets auflisten:**
```http
GET /api/v1/tenants/{tenantSlug}/media
```

**Neue Medien hinzufügen:**
```http
POST /api/v1/tenants/{tenantSlug}/media
```
(Datei-Upload oder externe URL)

**Media löschen:**
```http
DELETE /api/v1/media/{id}
```

---

## Playlist Management (JSON API)

**Playlist abrufen (Admin):**
```http
GET /api/v1/playlists/{screenId}
```

**Playlist abrufen (Player):**
```http
GET /api/v1/screens/{screenId}/playlist
```
(Gibt nur aktive Items zurück)

**Items verwalten:**
```http
POST   /api/v1/playlists/{playlistId}/items
PATCH  /api/v1/items/{itemId}
DELETE /api/v1/items/{itemId}
```

**Playlist konfigurieren:**
```http
PUT   /api/v1/playlists/{playlistId}/order
PATCH /api/v1/playlists/{playlistId}/duration
```

---

## Screen Management (JSON API)

**Self-Registration (Agent):**
```http
POST /api/v1/screens/register
```

**Screens eines Tenants auflisten:**
```http
GET /api/v1/tenants/{tenantSlug}/screens
```

**Screen erstellen (Admin):**
```http
POST /api/v1/tenants/{tenantSlug}/screens
```

---

## System & Health

**Health-Check:**
```http
GET /healthz
```

**API-Entrypoint:**
```http
GET /api/v1
```

**Metainformationen:**
```http
GET /api/v1/meta
```

---

## Player Local UI (auf dem Gerät)

**Player-Seite öffnen:**
```http
GET /player
```

**Aktuelle Playlist für lokale Anzeige:**
```http
GET /api/now-playing
```

**Systeminformationen anzeigen:**
```http
GET /api/sysinfo
```

---

## Status-Diagnose (Detailed)

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

```http
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:
```json
{
  "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)