Conventions JSON

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

Ports

Port	Interface	Version
10001	HTTP REST + WebSocket (canal de simulation)	v3.1 (version actuelle)
10020	WebSocket (canal d'événements, en 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 enveloppe :

La réussite (grâce aux données) :

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

Succès (aucune donnée — critères d'évaluation liés uniquement aux mutations) :

{ "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	Erreur de requête — 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 un session clé pour les commandes au niveau de la session.

Client → service (commande) :

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

Service → client (statut) :

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

Le premier message envoyé par le service comprend config (instantané complet) ; les messages suivants ne contiennent que state et status. Voir Protocole WebSocket pour découvrir 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 en texte clair.

Clés inconnues

Les touches inconnues sont ignorées sans avertissement

Actuellement, le service ignore 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 en vous référant à la documentation de l'API. Il est prévu de modifier ce comportement dans une prochaine version (les clés inconnues déclencheront alors un événement d'avertissement).