본문으로 바로 가기

JSON 규약

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

항구​

항구인터페이스버전
10001HTTP REST + WebSocket (시뮬레이션 채널)v3.1 (최신 버전)
10020WebSocket (이벤트 채널, 읽기 전용)—
10000레거시 웹소켓 (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": { … } }
  ]
}

Dienst → 클라이언트 (상태):

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

이 서비스에서 보낸 첫 번째 메시지에는 다음 내용이 포함되어 있습니다. config (전체 스냅샷); 이후의 뉴스에는 다음 내용만 포함됩니다 state 그리고 status. 참조 WebSocket 프로토콜 전체 진행 과정을 보려면.

콘텐츠 유형​

본문이 포함된 모든 HTTP 요청은 Content-Type: application/json 전송. WebSocket 메시지는 항상 단순한 일반 텍스트 JSON 프레임입니다.

알 수 없는 키​

알 수 없는 키는 묵시적으로 무시됩니다.

현재 이 서비스는 알 수 없는 JSON 키를 오류 없이 무시합니다. 명령이 작동하지 않는 것처럼 보일 경우, 서비스 로그를 확인하고 필드 이름을 API 참조 문서와 비교해 보십시오. 이 동작은 향후 버전에서 변경될 예정입니다(알 수 없는 키가 발생하면 경고 이벤트가 트리거됩니다).