JSON-Konventionen

Alle Service-Schnittstellen verwenden JSON. Auf dieser Seite werden die gemeinsam genutzten Schemata dokumentiert.

Anschluss

Anschluss	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-Antwortkapselung

Jede HTTP-Antwort verwendet dasselbe Format:

Erfolg (einschließlich Daten):

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

Erfolg (keine Daten – nur Endpunkte der Klasse „Änderung“):

{ "ok": true }

Fehler:

{ "ok": false, "error": "reason string" }

Veraltete Endpunkte:

{ "ok": true, "deprecation_warning": "This route is deprecated. Use …" }

HTTP-Statuscodes

Code	Bedeutung
200	Erfolg
400	Fehler bei der Anfrage – ungültiger Anfrageinhalt, mehrdeutiger Selektor, fehlende Pflichtfelder
404	Es wurden keine Geräte, Sitzungen oder Ressourcen gefunden.
405	Unzulässige Methoden

WebSocket-Nachrichtenformat

Die Nachricht ist ein JSON-Objekt. Der oberste Schlüssel ist der Name der Gerätegruppe (inverse3、verse_grip、wireless_verse_grip) sowie optionale Befehle auf Sitzungsebene session Taste.

Client → Dienst (Befehl):

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

Dienste → Client (Status):

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

Die erste Nachricht des Dienstes enthält config(vollständiger Schnappschuss); weitere Meldungen enthalten lediglich state und status。Den vollständigen Ablauf finden Sie unter WebSocket-Protokoll。

Inhaltstyp

Alle HTTP-Anfragen mit einem Anfragetext müssen gesendet werden Content-Type: application/json。 WebSocket-Nachrichten bestehen stets aus JSON-Frames im Klartext.

Unbekannter Schlüssel

Unbekannte Tasten werden stillschweigend ignoriert.

Der Dienst ignoriert derzeit nicht erkannte JSON-Schlüssel, ohne eine Fehlermeldung auszugeben. Sollte ein Befehl keine Wirkung zu zeigen scheinen, überprüfen Sie bitte die Protokolle des Dienstes und vergleichen Sie die Feldnamen mit der API-Referenz. Dieses Verhalten soll in zukünftigen Versionen geändert werden (unbekannte Schlüssel werden dann eine Warnmeldung auslösen).