Spécifications JSON

Toutes les interfaces de service utilisent le format JSON. Cette page décrit les schémas partagés.

Port

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

Encapsulation des réponses HTTP

Chaque réponse HTTP utilise le même format d'encapsulation :

Réussite (avec données) :

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

Succès (aucune donnée — uniquement les points de terminaison de type « modification ») :

{ "ok": true }

Erreur :

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

Points de terminaison obsolètes :

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

Codes d'état HTTP

Code	Signification
200	Succès
400	Erreur de requête : corps de la requête non valide, sélecteur ambigu, champs obligatoires manquants
404	Aucun périphérique, aucune session ni aucune ressource n'a été trouvé(e)
405	Méthodes non autorisées

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), ainsi que des options pour les commandes au niveau de la session session Touche.

Client → Service (commande) :

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

Services → Client (état) :

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

Le premier message du service contient config(instantané complet) ; les messages suivants ne contiennent que state et status. Pour connaître la procédure complète, veuillez consulter Protocole WebSocket。

Type de contenu

Toutes les requêtes HTTP comportant un corps doivent être envoyées Content-Type: application/json。 Les messages WebSocket sont toujours des trames JSON au format texte brut.

Clé inconnue

Les clés inconnues seront ignorées sans avertissement.

Le service ignore actuellement les clés JSON non reconnues, sans générer d'erreur. Si une commande semble ne pas fonctionner, veuillez consulter les journaux du service et vérifier les noms des champs en vous référant à la documentation de l'API. Ce comportement devrait être modifié dans les prochaines versions (les clés inconnues déclencheront alors un événement d'avertissement).