JSON-Konventionen

Alle Dienstschnittstellen verwenden JSON. Auf dieser Seite werden die gemeinsamen Muster beschrieben.

Anschlüsse

Hafen	Schnittstelle	Version
10001	HTTP REST + WebSocket (Simulationskanal)	v3.1 (aktuell)
10020	WebSocket (Ereigniskanal, schreibgeschützt)	—
10000	Legacy-WebSocket (v3.0 – wird in v4.0 entfernt)	v3.0

HTTP-Antwortstruktur

Jede Antwort von HTTP weist dieselbe Struktur auf:

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 Anfragetext, mehrdeutiger Selektor, fehlendes Pflichtfeld
404	Gerät, Sitzung oder Ressource nicht gefunden
405	Methode nicht zulässig

WebSocket-Nachrichtenformat

Nachrichten sind JSON-Objekte. Die Schlüssel der obersten Ebene sind die Namen der Gerätegruppen (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 (Status):

{
  "session_id": 7,
  "inverse3": [
    { "device_id": "049D", "config": { … }, "state": { … }, "status": { … } }
  ]
}

Die erste Nachricht des Dienstes enthält config (vollständiger Snapshot); nachfolgende Meldungen enthalten nur state und status. Siehe WebSocket-Protokoll für den vollständigen Ablauf.

Inhaltstyp

Alle HTTP-Anfragen mit Anfragetext müssen Content-Type: application/json senden. WebSocket-Nachrichten sind immer einfache JSON-Frames im Klartext.

Unbekannte Schlüssel

Unbekannte Schlüssel werden stillschweigend ignoriert

Der Dienst ignoriert derzeit unbekannte JSON-Schlüssel ohne Fehlermeldung. Wenn ein Befehl scheinbar keine Wirkung zeigt, überprü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 Warnereignis aus).