Conventions JSON
Toutes les interfaces de service utilisent le format 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 | Legacy-WebSocket (v3.0 — sera supprimé dans la version v4.0) | v3.0 |
Structure des réponses HTTP
Chaque réponse HTTP suit la même structure :
La réussite (grâce aux données) :
{ "ok": true, "data": { … } }
Succès (sans données – critères d'évaluation basés uniquement sur les changements) :
{ "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 non valide — corps de requête 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 niveau supérieur correspondent aux noms des groupes d'appareils
(inverse3, verse_grip, wireless_verse_grip) et une clé facultative session
pour les commandes liées à 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 contient config (instantané complet) ; les
messages suivants ne contiennent que state et status. Voir
Protocole WebSocket pour le déroulement complet.
Type de contenu
Toutes les requêtes HTTP comportant un corps de requête doivent Content-Type: application/json envoyer.
Les messages WebSocket sont toujours de simples trames JSON en clair.
Clés inconnues
Le service ignore actuellement les clés JSON inconnues sans générer d'erreur. Si une commande semble ne produire aucun effet, consultez les journaux du service et comparez les noms des champs avec la documentation de l'API. Ce comportement devrait être modifié dans une prochaine version (les clés inconnues déclencheront alors un événement d'avertissement).