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 参考 核实字段名称。 该行为计划在未来版本中改变（未知键将触发警告事件）。