Catalog REST API 시작하기

​

API 범위

/v1/projects/{projectId}/catalogs

• 데이터 소스가 api입니다.
• 데이터 분류가 non_personal입니다.
• 상태가 active입니다.

• 카탈로그: 생성, 목록, 영구 삭제. 단건 조회와 이름·설명·스키마 전체 수정은 지원하지 않습니다.
• 필드: 추가와 삭제. 이름·타입 수정은 지원하지 않습니다.
• 아이템: 단건·일괄 생성, 조회, 전체 교체, 부분 수정, 삭제
• 셀렉션: 생성과 삭제. 목록·단건 조회·수정은 지원하지 않습니다.

​

인증

Authorization: Bearer <auth-token>
Content-Type: application/json

​

기본 흐름

​

1. 카탈로그 만들기

{
  "catalogs": [
    {
      "name": "products",
      "description": "메시지 개인화용 상품 정보",
      "data_classification": "non_personal",
      "fields": [
        { "name": "id", "type": "string" },
        { "name": "name", "type": "string" },
        { "name": "price", "type": "number" },
        { "name": "tags", "type": "array" }
      ]
    }
  ]
}

​

2. 아이템 넣기

{
  "items": [
    {
      "id": "sku-1001",
      "name": "코튼 셔츠",
      "price": 39000,
      "tags": ["summer", "shirt"]
    }
  ]
}

​

3. 조회하고 페이지 이동하기

• next_cursor는 해석하지 말고 다음 요청의 cursor query parameter에 그대로 전달합니다.
• next_cursor가 null이면 마지막 페이지입니다.

​

셀렉션 필터

• string: equals, does not equal
• number: 위 두 연산자와 greater than, less than
• boolean: is
• time: before, after
• array: includes value, does not include value
• geo, object: 필터 미지원

​

쓰기 메서드 선택

{
  "items": [
    {
      "id": "sku-1001",
      "tags": {
        "$add": ["sale"],
        "$remove": ["summer"]
      }
    }
  ]
}

​

응답과 오류

{
  "data": {},
  "error": null
}

• 400: 프로젝트 ID 형식, 요청 스키마나 필드 값을 고친 뒤 다시 요청합니다.
• 401: 인증 토큰을 새로 발급받습니다.
• 403: 프로젝트 ID와 접근 권한을 확인합니다.
• 404: 카탈로그, 필드, 아이템 또는 셀렉션 이름을 확인합니다.
• 409: 중복 생성이나 현재 상태와 충돌한 요청입니다. 지원되는 목록·단건 조회 또는 호출자의 체크포인트로 상태를 확인합니다.
• 413: 4 MiB보다 작은 batch로 나눕니다.
• 500 또는 응답을 받지 못한 timeout: POST는 목록·단건 조회로 반영 여부를 먼저 확인하고 빠진 리소스만 재시도합니다. 전체 값을 반복 적용해도 되는 아이템은 PUT을 사용하고, 재시도 간격은 지수 방식으로 늘리면서 무작위 지연을 더합니다.

​

주요 제한

• 활성 카탈로그: 프로젝트당 최대 20개
• API 카탈로그 필드: id 포함 최대 500개
• 필드 추가: 한 요청에 최대 50개
• 아이템 쓰기·삭제: 한 요청에 최대 50개
• 아이템 하나: 최대 1 MiB
• 카탈로그 하나: 최대 2 GiB
• 활성 카탈로그 전체: 프로젝트당 최대 15 GiB
• 문자열 값: 최대 5,000자
• 배열 값: 문자열 최대 100개
• object·array 중첩: 최대 50단계
• object 필드에 저장하는 key: . 또는 $ 사용 불가. 배열 필드를 PATCH할 때 쓰는 $add와 $remove만 예외입니다.
• 셀렉션: 카탈로그당 최대 30개, 요청당 필터 최대 4개