# API Documentation Index

Vollständige Übersicht der Dokumentation für die morz-infoboard Backend-API.

---

## Einstieg

**Für Schnellzugriff auf spezifische Endpoints:**
→ **[API Quick Reference](API-QUICK-REFERENCE.md)**

Sortiert nach Funktion mit Kurzbeschreibungen und typischen Workflows.

---

## Vollständige Dokumentation

### [API-ENDPOINTS.md](API-ENDPOINTS.md)

Detaillierte Dokumentation aller HTTP-Endpoints mit:
- Request/Response-Beispielen
- Query-Parametern und Validierung
- HTTP-Status-Codes
- Fehlerehandlung

**Bereiche:**
- Health & Meta
- Player Status (Diagnose)
- Screen Management (JSON API)
- Playlist Management (JSON API)
- Media Management (JSON API)
- Admin UI (Web-Formulare)
- Playlist Management UI (Web-Formulare)
- Player Local UI (Agent)

### [PLAYER-STATUS-HTTP.md](PLAYER-STATUS-HTTP.md)

Spezialisierte Dokumentation für Status-Reporting:
- Status-Ingest vom Player-Agent
- Status-Abruf und Filterung
- Serverseitig abgeleitete Felder (stale, derived_state)
- Persistenz-Modell
- Agentseitige Connectivity-Ableitung

---

## Konzeptdokumentation

### [SERVER-KONZEPT.md](SERVER-KONZEPT.md)

Architektur und fachliche Bereiche:
- Server-Aufgaben und Komponenten
- Mandanten und Benutzer
- Screen-, Medien-, Playlist-Verwaltung
- Templates und Kampagnen
- Provisionierung
- Revisionsmodell
- Docker-Compose-Struktur

### [SCHEMA.md](SCHEMA.md)

Relationales Datenmodell mit:
- Tabellen-Definitionen (SQL)
- Primary/Foreign Keys
- Constraints und Indizes
- Prioritätslogik
- Zukunftserweiterungen

---

## Implementierungsdokumentation

### Code-Struktur

Backend-API ist in Go implementiert:
```
server/backend/internal/httpapi/
├── router.go              — Haupt-Router, Route-Registrierung
├── playerstatus.go        — Status-Endpoints
├── statuspage.go          — HTML-Diagnoseseiten
├── messagewall.go         — Message-Wall-Auflösung
├── manage/
│   ├── register.go        — Screen-Registrierung
│   ├── playlist.go        — Playlist-Management
│   ├── media.go           — Media-Management
│   └── ui.go              — Admin- & Manage-UI
```

Player-Agent hat lokale UI:
```
player/agent/internal/playerserver/
└── server.go              — Lokale Player-UI und Status-APIs
```

---

## Typische Anfragen

**Wie registriert sich ein Agent automatisch?**
→ Siehe [API-ENDPOINTS.md](API-ENDPOINTS.md) → Screen Management → `POST /api/v1/screens/register`

**Wie ruft der Player seine Inhalte ab?**
→ Siehe [API-ENDPOINTS.md](API-ENDPOINTS.md) → Playlist Management → `GET /api/v1/screens/{screenId}/playlist`

**Welche Status-Filteroptionen gibt es?**
→ Siehe [PLAYER-STATUS-HTTP.md](PLAYER-STATUS-HTTP.md) → Query-Parameter

**Wie lautet das Datenbankschema?**
→ Siehe [SCHEMA.md](SCHEMA.md)

**Wie läuft die Provisionierung ab?**
→ Siehe [SERVER-KONZEPT.md](SERVER-KONZEPT.md) → Provisionierung

---

## Änderungshistorie der Dokumentation

| Datum | Datei | Änderung |
|-------|-------|----------|
| 2026-03-23 | API-ENDPOINTS.md | Initiale vollständige Endpoint-Dokumentation erstellt |
| 2026-03-23 | API-QUICK-REFERENCE.md | Schnellreferenz mit Workflows hinzugefügt |
| 2026-03-23 | API-INDEX.md | Dokumentations-Index erstellt |
| 2026-03-23 | PLAYER-STATUS-HTTP.md | Link zur vollständigen API-Dokumentation hinzugefügt |

---

## Fehlende oder unvollständige Bereiche

- **MQTT-Integration:** Noch keine dedizierte Dokumentation für MQTT-Topics und Protokolle
- **Authentifizierung & Autorisierung:** Noch nicht implementiert (v1)
- **Rate Limiting:** Noch nicht spezifiziert
- **Transaktions-Semantik:** Noch nicht dokumentiert
- **Webhook/Event-System:** Geplant für spätere Phase
- **Provisioning Worker Details:** Noch nicht öffentlich dokumentiert

---

## Best Practices

### Für Agent-Implementierung

1. **Registrierung:** Rufe `POST /api/v1/screens/register` auf dem Startup auf
2. **Playlist-Polling:** Hole alle 30 Sekunden `GET /api/v1/screens/{screenId}/playlist` ab
3. **Status-Reporting:** Sende alle 30 Sekunden `POST /api/v1/player/status` ab
4. **Fehlerbehandlung:** HTTP-Fehler sollten zu lokaler Fallback-Playlist führen

### Für Admin-Panel

1. **Status-Überwachung:** Nutze `GET /status` (HTML) oder `GET /api/v1/screens/status` (JSON)
2. **Batch-Operations:** Für Multisel-Operationen empfohlen: Mehrere API-Requests statt Formulare
3. **Filterung:** Nutze Query-Parameter für `GET /api/v1/screens/status` zur Filterung

### Für Tenant-UI

1. **Medien-Verwaltung:** Nutze Multipart-Upload in `POST /api/v1/tenants/{tenantSlug}/media`
2. **Playlist-Bearbeitung:** Nutze JSON-API (`/api/v1/playlists/*`) für programmatische Zugriffe
3. **Validierung:** Prüfe gültige `duration_seconds` (> 0) und Medientypen

---

## Kontakt & Support

Für Fragen zur API-Dokumentation:
- Siehe [OFFENE-ARCHITEKTURFRAGEN.md](OFFENE-ARCHITEKTURFRAGEN.md)
- Code-Review in `/server/backend/internal/httpapi/`