JSONの規約

すべてのサービスインターフェースはJSONを使用しています。このページでは、共通のパターンについて説明しています。

ポート

ポート	インターフェース	バージョン
10001	HTTP REST + WebSocket（シミュレーションチャネル）	v3.1（最新版）
10020	WebSocket（イベントチャネル、読み取り専用）	—
10000	従来のWebSocket（v3.0 — v4.0で廃止予定）	v3.0

HTTPレスポンスエンベロープ

すべてのHTTPレスポンスは、同じエンベロープを使用します：

成功（データに基づく）：

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

成功（データなし — 変異のみを評価項目とする）：

{ "ok": true }

エラー：

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

非推奨のエンドポイント：

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

HTTPステータスコード

コード	意味
200	成功
400	不正なリクエスト — ボディが無効、セレクタが曖昧、必須フィールドが欠落しています
404	デバイス、セッション、またはリソースが見つかりません
405	このメソッドは使用できません

WebSocketメッセージの形式

メッセージはJSONオブジェクトです。最上位のキーはデバイスグループ名です (inverse3, verse_grip, wireless_verse_grip) およびオプションの session セッションレベルのコマンド用のキー。

クライアント → サービス（コマンド）：

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

サービス → クライアント（状態）：

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

このサービスからの最初のメッセージには、以下の内容が含まれています config （完全なスナップショット）；その後の メッセージには以下の内容のみが含まれます state そして status. 参照 WebSocketプロトコル ワークフローの全容については。

コンテンツの種類

本文を含むすべてのHTTPリクエストは、以下を送信する必要があります Content-Type: application/json. WebSocketメッセージは、常にプレーンテキストのJSONフレームです。

不明なキー

不明なキーは黙って無視されます

現在、本サービスでは認識されないJSONキーをエラーを出さずに無視します。 コマンドが効果を発揮していないと思われる場合は、サービスのログを確認し、 APIリファレンスと照らし合わせてフィールド名を確認してください。 この動作は今後のバージョンで変更される予定です（未知のキーが 警告イベントをトリガーするようになります）。