JSON-Konventionen
Alle Dienstschnittstellen verwenden JSON. Diese Seite beschreibt die gemeinsamen Muster.
Ports
| Port | Schnittstelle | Version |
|---|---|---|
| 10001 | HTTP REST + WebSocket (Simulationskanal) | v3.1 (aktuell) |
| 10020 | WebSocket (Ereigniskanal, nur lesend) | — |
| 10000 | Legacy-WebSocket (v3.0 — wird in v4.0 entfernt) | v3.0 |
HTTP-Antwortstruktur
Jede Antwort von HTTP verwendet dieselbe Struktur:
Erfolg (mit Daten):
{ "ok": true, "data": { … } }
Erfolg (ohne Daten – reine Änderungsendpunkte):
{ "ok": true }
Fehler:
{ "ok": false, "error": "reason string" }
Veralteter Endpunkt:
{ "ok": true, "deprecation_warning": "This route is deprecated. Use …" }
HTTP-Statuscodes
| Code | Bedeutung |
|---|---|
200 | Erfolg |
400 | Ungültige Anfrage — ungültiger Anfragekörper, mehrdeutiger Selektor, fehlendes Pflichtfeld |
404 | Gerät, Sitzung oder Ressource nicht gefunden |
405 | Methode nicht erlaubt |
WebSocket-Nachrichtenformat
Nachrichten sind JSON-Objekte. Die Schlüssel der obersten Ebene sind Gerätegruppennamen
(inverse3, verse_grip, wireless_verse_grip) und ein optionaler Schlüssel session
für sitzungsbezogene Befehle.
Client → Dienst (Befehl):
{
"session": { "configure": { … } },
"inverse3": [
{ "device_id": "049D", "configure": { … }, "commands": { … } }
]
}
Dienst → Client (Zustand):
{
"session_id": 7,
"inverse3": [
{ "device_id": "049D", "config": { … }, "state": { … }, "status": { … } }
]
}
Die erste Nachricht vom Dienst enthält config (vollständiger Snapshot); anschließende
Nachrichten enthalten nur state und status. Siehe
WebSocket-Protokoll für den vollständigen Ablauf.
Inhaltstyp
Alle HTTP-Anfragen mit Anfragekörper müssen Content-Type: application/json senden.
WebSocket-Nachrichten sind immer einfache Klartext-JSON-Frames.
Unbekannte Schlüssel
Der Dienst ignoriert derzeit unbekannte JSON-Schlüssel ohne Fehler. Wenn ein Befehl scheinbar keine Wirkung hat, prüfen Sie die Dienstprotokolle und vergleichen Sie die Feldnamen mit der API-Referenz. Dieses Verhalten soll in einer zukünftigen Version geändert werden (unbekannte Schlüssel lösen dann ein Warnungsereignis aus).