Règles communes pour le format JSON

Toutes les interfaces de service utilisent le format JSON. Cette page présente les modèles courants.

Port

Port	Interface	Version
10001	HTTP REST + WebSocket (canal de simulation)	v3.1 (actuelle)
10020	WebSocket (canal d'événements, lecture seule)	—
10000	WebSocket hérité (v3.0 — devant être supprimé dans la version v4.0)	v3.0

Enveloppe de réponse HTTP

Toutes les réponses HTTP utilisent la même enveloppe :

Réussite (données incluses) :

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

Succès (aucune donnée, point de terminaison en lecture seule) :

{ "ok": true }

Erreur :

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

Points d'accès désactivés :

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

Codes d'état HTTP

Code	Signification
200	succès
400	Demande incorrecte — Le corps de la demande est incorrect, le sélecteur est ambigu ou un champ obligatoire est manquant.
404	Impossible de trouver le périphérique, la session ou la ressource
405	Méthode non autorisée

Format des messages WebSocket

Le message est un objet JSON. La clé de niveau supérieur correspond au nom du groupe d'appareils (inverse3, verse_grip, wireless_verse_grip) et une option pour les commandes au niveau de la session session Vous pouvez utiliser la touche.

Client → Service (commande) :

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

Service → Client (état) :

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

Le premier message envoyé par le service contient config(un instantané complet) est inclus. Les messages suivants contiennent stateWa status... sont inclus. Le flux de travail complet est le suivant : Protocole WebSocketVeuillez vous reporter à [...].

Type de contenu

Toute requête HTTP comportant un corps est Content-Type: application/jsonIl faut les transmettre. Les messages WebSocket sont toujours des trames JSON en texte clair.

Clé inconnue

Les clés inconnues sont simplement ignorées.

Le service ignore sans générer d'erreur les clés JSON qu'il ne reconnaît pas pour le moment. Si une commande semble ne produire aucun effet, veuillez vérifier les journaux du service et vous assurer que le nom du champ correspond à celui indiqué dans la documentation de l'API. Ce comportement est susceptible d'évoluer dans les prochaines versions (les clés inconnues déclencheront alors un événement d'avertissement).