aff12a4d81
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>
165 lines
4.9 KiB
Markdown
165 lines
4.9 KiB
Markdown
# 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/`
|