API 레퍼런스

이 페이지의 내용

Base URL#

모든 Endpoint는 https://api.structly.io의 /api 아래에 있습니다. stly와 Web UI도 같은 API를 사용합니다. Tag별 Endpoint는 왼쪽 메뉴의 API 레퍼런스 아래 페이지에서 확인합니다.

인증#

방식	전달	Catalog 범위
세션 쿠키	로그인 후 받는 `structly_session` 쿠키	현재 선택한 Organization
Agent 토큰	`Authorization: Bearer <토큰>` 헤더	토큰이 속한 Organization

인증 검사는 경로·Method·입력 검사보다 먼저 합니다.
쿠키로 인증한 상태 변경 요청은 Origin이 서버 origin과 같아야 합니다. 다르면 403 FORBIDDEN_ORIGIN입니다.
세션에 현재 Organization이 없으면 409 ORGANIZATION_REQUIRED, 인증 대기 Organization이면 403 ORGANIZATION_UNVERIFIED입니다.
다른 Organization의 ID는 404로 응답합니다.

stly에서 Agent 토큰을 쓰는 방법은 stly 로그인과 인증을 참고합니다.

오류 응답#

오류는 HTTP 상태와 함께 다음 필드를 최상위에 반환합니다.

필드	내용
`code`	`{상태}.000` 형식의 코드
`reason`	오류 원인의 고정 식별자. 분기에는 이 값을 씁니다
`message`	표시용 설명. 문자열 일치로 분기하지 않습니다
`data`	필드별 오류 배열. 필드 오류가 없으면 빈 배열입니다

{"code":"412.000","reason":"PRECONDITION_FAILED","message":"요청을 처리할 수 없습니다.","data":[]}

문서에 없는 /api 경로는 404 ROUTE_NOT_FOUND, 지원하지 않는 Method는 405 METHOD_NOT_ALLOWED와 Allow 헤더입니다.
모든 응답은 캐시하지 않습니다(Cache-Control: no-store).

ETag와 If-Match#

상세 GET은 strong ETag 헤더를 반환합니다. PUT·DELETE는 그 값을 단일 If-Match 헤더로 보내야 합니다. 없으면 428 PRECONDITION_REQUIRED, 그 사이 다른 변경이 저장되었으면 412 PRECONDITION_FAILED입니다. 충돌 처리 순서는 동시 수정 충돌을 참고합니다.

레퍼런스 읽는 법#

Tag 페이지는 Endpoint마다 Method·Path, 인증, Parameter, 요청 본문, 응답 상태와 성공 응답 본문을 표시합니다.
요청·응답 본문 표는 최상위 필드만 보여 줍니다. 하위 객체는 타입 이름으로 표시합니다.
설명은 공개 계약의 원문(한국어)입니다.