3Min API

API 연동

API 연동에 필요한 기술 사양입니다.

1. 기본 URL

엔드포인트 URL은 엔드포인트 상세 페이지에서 확인할 수 있습니다.

POST
https://api.chikage.io/api/v1/data/{slug}
GET / PUT / DELETE
https://api.chikage.io/api/v1/data/{slug}/{record_id}

2. 인증

API 키를 헤더에 포함하세요.

헤더설명필수
AuthorizationBearer tm_test_xxx... / Bearer tm_live_xxx...Yes
Content-Typeapplication/jsonYes
X-Webhook-Callback웹훅 URLNo
X-Webhook-Auth인증 값 (예: Bearer 토큰)No
X-Webhook-Auth-Header인증 헤더 이름No

3. 요청 형식

  • Content-Type: application/json만 허용
  • 최대 크기: 요청당 100KB
  • 메서드: POST / GET / PUT / DELETE

CRUD 엔드포인트

각 엔드포인트는 네 가지 HTTP 메서드를 자동으로 지원합니다:

메서드경로설명
POST/api/v1/data/{slug}새 레코드 생성 (비동기, 큐 처리)
GET/api/v1/data/{slug}/{record_id}ID로 레코드 조회
PUT/api/v1/data/{slug}/{record_id}ID로 레코드 교체 (비동기, 큐 처리)
DELETE/api/v1/data/{slug}/{record_id}ID로 레코드 삭제 (비동기, 큐 처리)

GET, PUT, DELETE는 이전 POST 응답에서 반환된 레코드 ID가 필요합니다.

POST — 생성:

curl -X POST https://api.chikage.io/api/v1/data/{slug} \
  -H "Authorization: Bearer tm_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "ORD-2024-001",
  "amount": 45000,
  "items": ["Item A", "Item B"],
  "paid": true
}'

GET — 조회:

curl https://api.chikage.io/api/v1/data/{slug}/rec_abc123 \
  -H "Authorization: Bearer tm_test_xxx"

PUT — 수정:

curl -X PUT https://api.chikage.io/api/v1/data/{slug}/rec_abc123 \
  -H "Authorization: Bearer tm_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "ORD-2024-001",
  "amount": 50000,
  "items": ["Item A", "Item B", "Item C"],
  "paid": true
}'

DELETE — 삭제:

curl -X DELETE https://api.chikage.io/api/v1/data/{slug}/rec_abc123 \
  -H "Authorization: Bearer tm_test_xxx"

4. 응답 형식

성공 응답 (202):

{
  "success": true,
  "id": "rec_abc123",
  "message": "Request queued"
}

에러 응답 예시 (400):

{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "field": "order_id", "error": "Required field is missing" }
  ]
}

에러 응답:

CodeStatusDescription
400잘못된 요청잘못된 JSON 또는 필수 필드 누락
401인증 실패API 키가 없거나 유효하지 않음, 또는 소유자가 키를 비활성화
403접근 거부엔드포인트 비활성 또는 구독 만료
415지원하지 않는 미디어 타입Content-Type은 application/json이어야 함
429요청 한도 초과월간 사용량 한도 초과
5xx서버 오류내부 서버 오류 (500, 502, 503 등)

5. 협업자 웹훅

API 협업자가 직접 처리 결과를 받을 수 있습니다.

재시도 정책: 실패 시 최대 3회 재시도 (60초 간격)

6. 테스트 도구

실서비스 전 샌드박스에서 테스트하세요.

  • 내장 테스트 페이지: 엔드포인트 상세 페이지의 테스트 버튼으로 진입 — 별도 도구 불필요
  • cURL: 명령줄에서 테스트
  • Postman: API 테스트 도구 사용

7. 프로덕션 콘솔

프로덕션 배포 후, 엔드포인트 소유자는 외부 API 도구나 코드 없이 대시보드에서 직접 프로덕션 데이터를 관리할 수 있습니다.

접근 방법

엔드포인트 상세 → 프로덕션 탭 → "콘솔 열기" 클릭 시 새 탭에서 열립니다.

기능

  • 프로덕션 데이터에 대한 전체 CRUD 지원 (POST / GET / PUT / DELETE)
  • 프로덕션 API 키가 자동으로 설정됨 — 수동 입력 불필요
  • 콘솔에서의 요청은 웹훅을 트리거하지 않습니다

소유자 전용

프로덕션 콘솔은 엔드포인트 소유자만 접근할 수 있습니다. 협업자는 사용할 수 없습니다.