morz-infoboard/docs/API-INDEX.md

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

Sortiert nach Funktion mit Kurzbeschreibungen und typischen Workflows.

---

Vollständige Dokumentation

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

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

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

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 → Screen Management → POST /api/v1/screens/register

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

Welche Status-Filteroptionen gibt es? → Siehe PLAYER-STATUS-HTTP.md → Query-Parameter

Wie lautet das Datenbankschema? → Siehe SCHEMA.md

Wie läuft die Provisionierung ab? → Siehe 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
• Code-Review in /server/backend/internal/httpapi/