본문으로 바로 가기

JSON 공통 규칙

모든 서비스 인터페이스는 JSON을 사용합니다. 이 페이지에서는 일반적인 패턴을 설명합니다.

포트​

포트인터페이스버전
10001HTTP REST + WebSocket(시뮬레이션 채널)v3.1(현재)
10020WebSocket(이벤트 채널, 읽기 전용)—
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 참조 문서와필드 이름이 일치하는지 확인해 주십시오. 이 동작은 향후 버전에서 변경될 예정입니다(알 수 없는 키가 경고 이벤트를 발생시키도록 변경됩니다).