Conventions de JSON

Toutes les interfaces de service utilisent JSON. Cette page décrit les modèles communs.

Ports

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 — sera retiré dans la v4.0)	v3.0

Enveloppe de réponse HTTP

Chaque réponse HTTP utilise la même enveloppe :

Succès (avec données) :

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

Succès (sans données — points de terminaison de modification seulement) :

{ "ok": true }

Erreur :

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

Point de terminaison déprécié :

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

Codes d'état HTTP

Code	Signification
200	Succès
400	Requête incorrecte — corps invalide, sélecteur ambigu, champ obligatoire manquant
404	Appareil, session ou ressource introuvable
405	Méthode non autorisée

Format des messages WebSocket

Les messages sont des objets JSON. Les clés de premier niveau sont les noms des groupes d'appareils (inverse3, verse_grip, wireless_verse_grip) et une clé facultative session pour les commandes au niveau de la session.

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 du service inclut config (instantané complet) ; les messages suivants n'incluent que state et status. Voir le Protocole WebSocket pour le flux de travail complet.

Type de contenu

Toutes les requêtes HTTP avec un corps doivent envoyer Content-Type: application/json. Les messages WebSocket sont toujours des trames JSON en texte brut.

Clés inconnues

Les clés inconnues sont ignorées silencieusement

Le service ignore actuellement les clés JSON non reconnues, sans générer d'erreur. Si une commande semble sans effet, consultez les journaux du service et vérifiez les noms de champs dans la référence de l'API. Ce comportement doit changer dans une version future (les clés inconnues déclencheront un événement d'avertissement).