Allgemeine JSON-Regeln

Alle Service-Schnittstellen verwenden JSON. Auf dieser Seite werden gängige Muster erläutert.

Hafen

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-Antwort-Envelope

Alle HTTP-Antworten verwenden denselben Envelope:

Erfolg (einschließlich Daten):

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

Erfolg (keine Daten, Endpunkt nur für Änderungen):

{ "ok": true }

Fehler:

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

Nicht mehr verwendete Endpunkte:

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

HTTP-Statuscodes

Code	Bedeutung
200	Erfolg
400	Fehlerhafte Anfrage – Der Text ist fehlerhaft, der Selektor ist mehrdeutig oder ein Pflichtfeld fehlt.
404	Gerät, Sitzung oder Ressource nicht gefunden
405	Unzulässige Methode

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 eine optionale Funktion für Befehle auf Sitzungsebene session Sie können die Taste verwenden.

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, die vom Dienst gesendet wird, enthält config(Gesamt-Snapshot) ist enthalten. In den nachfolgenden Nachrichten steht stateWow status… sind enthalten. Der gesamte Arbeitsablauf umfasst WebSocket-ProtokollSiehe dazu.

Inhaltstyp

Jede HTTP-Anfrage mit Textinhalt ist Content-Type: application/jsonmüssen übertragen werden. WebSocket-Nachrichten sind immer JSON-Frames im Klartext.

Unbekannter Schlüssel

Unbekannte Tasten werden einfach ignoriert.

Der Dienst ignoriert derzeit nicht erkannte JSON-Schlüssel ohne Fehlermeldung. Sollte der Befehl keine Wirkung zu zeigen scheinen, überprüfen Sie bitte das Dienstprotokoll und vergewissern Sie sich, dass die Feldnamen mit der API-Referenzübereinstimmen. Dieses Verhalten wird sich in zukünftigen Versionen ändern (unbekannte Schlüssel werden dann eine Warnmeldung auslösen).