JSON-Konventionen

Alle Service-Schnittstellen 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	Alte WebSocket-Version (v3.0 – wird in v4.0 entfernt)	v3.0

HTTP-Antwort-Envelope

Jede HTTP-Antwort verwendet denselben Umschlag:

Erfolg (mit Daten):

{ "ok": true, "data": { … } }

Erfolg (keine Daten – Endpunkte, die ausschließlich auf Mutationen basieren):

{ "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	Fehlerhafte Anfrage – ungültiger Hauptteil, 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 optionales session Schlüssel für Befehle auf Sitzungsebene.

Client → Dienst (Befehl):

{
  "session": { "configure": { … } },
  "inverse3": [
    { "device_id": "049D", "configure": { … }, "commands": { … } }
  ]
}

Dienst → Kunde (Status):

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

Die erste Nachricht des Dienstes enthält config (vollständiger Schnappschuss); nachfolgende Nachrichten enthalten nur state und status. Siehe WebSocket-Protokoll für den gesamten Arbeitsablauf.

Inhaltstyp

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

Unbekannte Tasten

Unbekannte Schlüssel werden stillschweigend ignoriert

Der Dienst ignoriert derzeit unbekannte JSON-Schlüssel ohne Fehlermeldung. Falls ein Befehl keine Wirkung zu zeigen scheint, überprüfen Sie bitte 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 werden dann ein Warnereignis auslösen).