규약

최종 수정: 2026년 6월 22일

WEEGLOO API를 코드에서 호출할 때 모든 요청·응답에 공통으로 적용되는 HTTP 규약을 한곳에 정리합니다. 응답 미디어 타입, 부분 수정(JSON Patch), 동시 수정 충돌을 막는 X-Weegloo-Version 헤더가 여기에 해당합니다. 개별 리소스의 엔드포인트는 각 리소스 레퍼런스에서 다루고, 그 엔드포인트들이 공통으로 따르는 규약은 이 페이지를 참조합니다.

응답 미디어 타입

WEEGLOO API의 응답은 application/vnd.com.weegloo.v1+json;charset=UTF-8 미디어 타입을 씁니다. 일반 application/json이 아닙니다.

요청에 Accept: application/json을 보내지 마세요. 이 값으로 미디어 타입을 협상하면 WEEGLOO의 벤더 타입과 맞지 않아 406 Not Acceptable 같은 실패가 날 수 있습니다.

  • 권장: 요청에서 Accept 헤더를 생략합니다(예: fetch에 Accept를 넣지 않음).
  • 굳이 보내야 한다면 응답과 같은 벤더 타입 application/vnd.com.weegloo.v1+json;charset=UTF-8을 그대로 씁니다.

axios 인스턴스나 공통 fetch 래퍼를 만들 때 기본값이 Accept: application/json을 강제하지 않도록 합니다. (이 규칙은 애플리케이션 코드에 적용됩니다. AI 에이전트는 HTTP를 직접 호출하지 않고 MCP 도구를 씁니다.)

부분 수정 (JSON Patch)

Content·Media·Content Type 등 대부분의 리소스는 PATCH로 일부만 골라 수정할 수 있습니다. 본문은 RFC 6902 JSON Patch 형식의 배열입니다. 각 항목은 연산 op, 대상 위치를 가리키는 JSON Pointer 경로 path, 그리고 연산에 따라 value 또는 from을 가집니다.

PATCH 요청의 Content-Type 헤더는 application/json-patch+json이어야 합니다. 일반 application/json이 아닙니다.

다음은 한 필드의 값만 바꾸는 예시입니다.

[
  { "op": "replace", "path": "/fields/price/en-US", "value": 16500 }
]

전체 본문으로 바꾸려면 PUT을 씁니다. PUT은 리소스 전체 본문(또는 엔드포인트 계약이 허용하는 경우 바꿀 부분만 담은 부분 본문)으로 교체합니다. 어느 엔드포인트가 PATCH를 지원하는지, PUT이 전체 교체인지 부분 교체인지는 각 리소스 페이지의 엔드포인트 블록에서 확인하세요.

동시성 제어 (X-Weegloo-Version)

같은 리소스를 두 곳에서 동시에 고치면 한쪽 변경이 다른 쪽을 덮어쓸 수 있습니다. WEEGLOO는 이를 막기 위해 낙관적 동시성 제어를 씁니다. 리소스를 수정·삭제·상태 전환할 때, 요청에 현재 sys.version을 X-Weegloo-Version 헤더로 실어 보냅니다.

서버는 이 값이 저장된 현재 버전과 같을 때만 변경을 받아들입니다. 헤더가 빠지거나 값이 어긋나면(그 사이 누군가 먼저 고쳐 버전이 올라간 경우 등) 충돌 오류 WGL409005로 거부됩니다. 이때는 리소스를 다시 조회해 최신 sys.version을 받은 뒤 변경을 재시도합니다. 오류 응답 형식은 에러에서 다룹니다.

어떤 요청에 필요한지는 다음과 같습니다.

구분X-Weegloo-Version
수정(PUT)·부분 수정(PATCH)필요
상태 전환(발행·발행취소·보관·보관해제)필요
생성(POST)없음
삭제(DELETE)일부만 필요

version이 없는 리소스(ServiceUser)는 이 헤더를 받지 않습니다. 정확히 어느 엔드포인트가 이 헤더를 요구하는지는 각 리소스 페이지의 엔드포인트 블록에 있는 requestHeaderSchema를 확인하세요. sys.version 자체의 의미는 시스템 속성 (sys)에서 다룹니다.