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 참조 문서를 대조하여 필드 이름을 확인해 주십시오. 이 동작은 향후 버전에서 변경될 예정입니다(알 수 없는 키가 발견되면 경고 이벤트가 발생합니다).