JSON の規約

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

ポート

ポート	インターフェース	バージョン
10001	HTTP REST + WebSocket（シミュレーションチャネル）	v3.1（現行）
10020	WebSocket（イベントチャネル、読み取り専用）	—
10000	レガシー WebSocket（v3.0 — v4.0 で削除予定）	v3.0

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

成功（データあり）：

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

成功（データなし — 変更専用のエンドポイント）：

{ "ok": true }

エラー：

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

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

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

コード	意味
`200`	成功
`400`	不正なリクエスト — 本文が無効、セレクターが曖昧、必須フィールドが不足
`404`	デバイス、セッション、またはリソースが見つかりません
`405`	メソッドは許可されていません

メッセージは 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 リファレンスと照合してください。この動作は将来のバージョンで変更される予定です（不明なキーは警告イベントを発生させるようになります）。