Conventions JSON
Toutes les interfaces de service utilisent le format JSON. Cette page décrit les modèles courants.
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 supprimé dans la v4.0) | v3.0 |
Enveloppe de réponse HTTP
Chaque réponse HTTP utilise la même structure :
Succès (avec données) :
{ "ok": true, "data": { … } }
Succès (aucune donnée — points de fin de modification uniquement) :
{ "ok": true }
Erreur :
{ "ok": false, "error": "reason string" }
Point de terminaison obsolète :
{ "ok": true, "deprecation_warning": "This route is deprecated. Use …" }
Codes d'état HTTP
| Code | Signification |
|---|---|
200 | Succès |
400 | Requête incorrecte — corps non valide, 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 correspondent aux 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 comprend config (instantané complet) ; les messages suivants ne contiennent que state et status. Voir le
Protocole WebSocket pour l'ensemble du processus.
Type de contenu
Toutes les requêtes HTTP comportant un corps doivent envoyer Content-Type: application/json.
Les messages WebSocket sont toujours des trames JSON au format texte brut.
Clés inconnues
Le service ignore actuellement les clés JSON non reconnues, sans générer d'erreur. Si une commande semble ne produire aucun effet, consultez les journaux du service et vérifiez les noms des champs dans la documentation de l'API. Ce comportement devrait changer dans une prochaine version (les clés inconnues déclencheront un événement d'avertissement).