테스트 및 연동 가이드
개요
엔드포인트 상세 페이지에서 테스트하기 버튼을 누르면 열리는 페이지입니다. 별도의 도구 없이 브라우저에서 바로 API 호출을 테스트할 수 있고, 협업자에게 공유하면 연동에 필요한 정보를 한눈에 확인할 수 있어요.
이 페이지에서의 테스트는 샌드박스 환경에서만 진행됩니다. 프로덕션 데이터에는 영향을 주지 않으니 자유롭게 테스트하세요.
페이지는 두 개의 탭으로 구성되어 있습니다.
- 빠른 시작 — API 키 인증 후 바로 호출 테스트
- 가이드 — 소유자·협업자 역할별 연동 안내 (단계 가이드, API 엔드포인트, 헤더, 필드 정의, 코드 예시 등)
진입 경로
- 엔드포인트 상세 우측 사이드바 > 테스트하기 버튼 (Sandbox 탭)
- 협업자는 초대 수락 후 자신의 대시보드에서도 접근 가능
엔드포인트 정보
- 엔드포인트 이름과 설명이 표시됩니다
- 환경 배지(샌드박스)와 버전 정보가 함께 나타납니다
- 빠른 시작 / 가이드 탭을 전환할 수 있어요
빠른 시작 탭
인증
테스트를 시작하려면 먼저 API 키로 인증해야 합니다.
- API 키 입력란에 샌드박스 키(
tm_test_로 시작)를 붙여넣고인증버튼을 누르세요 - 사용할 수 있는 키는 두 가지입니다:
인증이 완료되면 입력란이 사라지고 로그아웃 버튼이 나타납니다. 다른 키로 테스트하고 싶다면 로그아웃 후 다시 인증하세요.
Try it out
인증이 완료되면 CRUD 호출을 바로 실행할 수 있는 영역이 활성화됩니다. 메서드를 선택하고 요청 본문(JSON)을 입력한 뒤 실행 버튼을 누르면 결과가 바로 표시돼요.
전체 흐름을 한 번에 테스트하고 싶다면 아래 순서대로 진행해 보세요.
CRUD 전체 테스트 가이드
CREATE (POST) — 요청 본문에 테스트 JSON을 입력하고 실행합니다. 응답에 포함된
id값을 복사해 두세요. 이후 단계에서 이 ID가 필요합니다.READ (GET) — 위에서 받은
id를 Record ID 입력란에 붙여넣고 실행합니다. 방금 생성한 데이터가 정상적으로 조회되는지 확인하세요.UPDATE (PUT) — 같은
id를 입력하고, 요청 본문에 수정할 JSON을 넣어 실행합니다. 전체 교체(full replacement) 방식이므로 변경할 필드뿐 아니라 유지할 필드도 함께 포함해야 합니다.DELETE — 같은
id를 입력하고 실행합니다. 이후 READ를 다시 시도하면 해당 레코드가 삭제된 것을 확인할 수 있어요.
권한 확인: 협업 키로 테스트하는 경우, 해당 키에 허용된 메서드만 실행할 수 있습니다. 권한이 없는 메서드를 호출하면 403 오류가 반환돼요. 권한 설정은 협업키 관리 > 권한에서 확인할 수 있습니다.
협업자 웹훅
Try it out 섹션 하단에 접힘 영역으로 웹훅 설정이 있습니다. 이것은 소유자가 대시보드에서 설정하는 웹훅과는 별개로, API를 호출하는 쪽에서 요청 헤더에 웹훅 정보를 포함하여 처리 결과를 받아보는 기능입니다. 여기서는 해당 헤더를 미리 테스트해 볼 수 있어요.
- 소유자 웹훅과 독립적으로 동작합니다
- 실제 연동 시에는 API 호출 코드에 웹훅 헤더를 직접 포함하여 구현합니다
- 자세한 헤더 이름과 구현 방식은 가이드 탭의 웹훅 설정 섹션을 참고하세요
가이드 탭
가이드 탭은 소유자와 협업자 모두가 연동 전체 흐름과 기술 세부 사항을 한 곳에서 확인할 수 있도록 구성되어 있습니다. 상단에는 역할별 단계 가이드, 하단에는 API 연동에 필요한 기술 레퍼런스가 이어집니다.
시작 가이드 — 소유자
엔드포인트를 만들었나요? 탭을 선택하면, 소유자 관점에서 진행해야 할 단계가 순서대로 안내됩니다.
- 엔드포인트 생성 — API 이름만 정하면 CRUD가 자동 생성됩니다. 설명과 필수 필드는 나중에 추가해도 됩니다
- 샌드박스 테스트 및 로그 확인 — 빠른 시작 탭에서 기본 API 키로 호출해 보고, 대시보드 로그에서 데이터 수신을 확인합니다
- 협업 키 생성 및 협업자 초대 — 협업 키를 만들고 상세 페이지에서 이메일 초대를 보냅니다
- 연동 테스트 — 협업자가 샌드박스에서 정상 호출하는지 로그로 함께 확인합니다
- 프로덕션 배포 — 협업자의 배포 요청을 승인하거나, 소유자가 직접 배포합니다. 배포 후 협업자에게 알림이 전달됩니다
시작 가이드 — 협업자
초대를 받았나요? 탭을 선택하면, 초대받은 협업자 관점에서 진행할 단계가 안내됩니다.
- 초대 수락 — 초대 이메일을 확인하고, 로그인 후 대시보드에서 수락합니다
- API 키 확인 — 엔드포인트 상세에서 샌드박스 API 키(
tm_test_)를 확인합니다 - 연동 및 테스트 — 빠른 시작 탭에서 호출을 테스트하고, 가이드 탭의 기술 정보를 참고해 연동을 개발합니다. 202 응답을 받았다면 이후 처리는 시스템이 보장합니다
- 배포 요청 — 테스트가 완료되면 엔드포인트 상세에서 배포 요청을 보냅니다
- 프로덕션 전환 — 소유자가 배포를 완료하면 알림을 받고, 프로덕션 API 키(
tm_live_)로 전환합니다
API 엔드포인트
이 엔드포인트에서 사용할 수 있는 API 경로와 메서드가 표시됩니다. 엔드포인트를 생성하면 다음 네 가지 메서드가 자동으로 준비됩니다.
| 메서드 | 경로 | 설명 |
|---|---|---|
| POST | /api/v1/data/{slug} |
새 레코드 생성 |
| GET | /api/v1/data/{slug}/{record_id} |
레코드 조회 |
| PUT | /api/v1/data/{slug}/{record_id} |
레코드 교체 |
| DELETE | /api/v1/data/{slug}/{record_id} |
레코드 삭제 |
{slug}는 엔드포인트 생성 시 자동으로 부여되는 고유 식별자이며, 이 페이지에서 실제 값을 확인할 수 있습니다.
API 키
API 호출 시 인증에 사용할 키 정보입니다.
| 환경 | 키 접두사 | 용도 |
|---|---|---|
| 샌드박스 | tm_test_ |
개발 및 테스트 |
| 프로덕션 | tm_live_ |
상용 서비스 |
프로덕션 API 키는 배포가 완료된 후에 엔드포인트 상세 페이지에서 확인할 수 있습니다. 배포 전에는 프로덕션 키로 호출해도 거부됩니다.
요청 헤더
API 호출 시 포함해야 하는 HTTP 헤더입니다. Content-Type과 Authorization은 필수이며, 웹훅 관련 헤더는 필요한 경우에만 추가합니다.
| 헤더 | 필수 여부 | 설명 |
|---|---|---|
Content-Type |
필수 | application/json (POST/PUT 요청 시) |
Authorization |
필수 | Bearer {API_KEY} 형식 |
X-Webhook-Callback |
선택 | 호출자 웹훅을 받을 URL |
X-Webhook-Auth |
선택 | 웹훅 인증 값 (예: Bearer 토큰) |
X-Webhook-Auth-Header |
선택 | 웹훅 인증 헤더 키 (기본값: Authorization) |
요청 본문
POST/PUT 요청 시 전송할 JSON 본문에 대한 안내입니다.
- 형식: JSON (
application/json) · 최대 100KB · UTF-8 - 소유자가 필수 필드를 정의한 경우, 해당 필드가 반드시 포함되어야 합니다. 필수 필드 외에 추가 필드도 자유롭게 함께 전송할 수 있어요
- 필수 필드가 정의되지 않았다면 어떤 JSON이든 받아들입니다
- 요청은 비동기로 처리됩니다. 즉시 202 응답을 받고, 실제 저장과 웹훅 전달은 백그라운드에서 진행돼요
응답 형식
각 메서드별 성공 응답과 주요 에러 코드가 표시됩니다.
성공 응답:
- POST/PUT/DELETE →
202 Accepted(요청이 수락되어 처리 대기열에 추가됨) - GET →
200 OK(데이터 즉시 반환)
주요 에러 코드:
| 코드 | 상태 | 의미 |
|---|---|---|
| 400 | 잘못된 요청 | JSON 형식 오류, 필수 필드 누락, 잘못된 레코드 ID |
| 401 | 인증 실패 | API 키가 없거나 유효하지 않음 |
| 403 | 접근 거부 | 엔드포인트 비활성, 구독 없음, 또는 권한 부족 |
| 415 | 지원하지 않는 미디어 타입 | Content-Type이 application/json이 아닌 경우 |
| 429 | 요청 한도 초과 | 월간 사용량 한도 초과 |
| 5xx | 서버 오류 | 서버 측 일시 오류 — 재시도 로직 구현 권장 |
5xx 에러를 받았다면 요청이 서버에 도달하지 못한 것이므로, 코드에 재시도 로직(예: 1s → 2s → 4s 백오프)을 구현하세요. 202 응답을 받았다면 이후 처리는 시스템이 보장합니다.
웹훅 설정
API를 호출하는 쪽에서 처리 결과를 자동으로 받아보고 싶을 때 사용하는 호출자 웹훅 설정 안내입니다. 소유자가 대시보드에서 설정하는 웹훅과는 별개로, 각각 독립적으로 동작합니다.
설정 방법: API 호출 시 요청 헤더에 다음을 포함합니다.
| 헤더 | 필수 여부 | 설명 |
|---|---|---|
X-Webhook-Callback |
필수 | 웹훅을 받을 URL |
X-Webhook-Auth |
선택 | 인증 값 (예: Bearer 토큰) |
X-Webhook-Auth-Header |
선택 | 인증 헤더 키 (기본값: Authorization) |
재시도 정책:
- 실패 시 최대 3회 재시도 (1~2초 백오프)
- 성공 기준: 2xx 상태 코드
- 3회 모두 실패해도 데이터는 안전하게 저장됩니다. 로그에서 웹훅 상태를 확인할 수 있어요
코드 예시
curl, JavaScript, Python 등 주요 언어별 API 호출 코드 샘플이 제공됩니다. 탭을 전환하면 각 언어에 맞는 예시를 확인할 수 있으며, 실제 엔드포인트 URL과 필수 헤더가 미리 채워져 있어 복사하여 바로 사용할 수 있어요.
자주 막히는 부분
- 인증 버튼을 눌렀는데 반응이 없어요: API 키가
tm_test_로 시작하는 샌드박스 키인지 확인하세요. 프로덕션 키(tm_live_)는 이 페이지에서 사용할 수 없습니다 - CREATE 후 ID를 잃어버렸어요: CREATE를 다시 호출하면 새 레코드가 생성되므로 이어서 테스트할 수 있어요. 이전에 생성한 레코드의 ID가 필요하다면 대시보드의 로그 페이지에서 해당 엔드포인트의 호출 기록을 확인하세요
- 403 오류가 나와요: 사용 중인 협업 키에 해당 메서드 권한이 없을 수 있습니다. 협업키 관리 > 권한에서 확인하세요
- 웹훅이 안 도착해요: 웹훅 서버가 7초 안에 응답하지 않으면 실패로 처리됩니다. 서버가 공개 인터넷에서 접근 가능한지, HTTPS를 사용하고 있는지 확인하세요. Discord나 Slack 같은 플랫폼은 자체 호출 횟수 제한(Rate Limit)이 있어서, 짧은 시간에 너무 많은 웹훅이 발생하면 일부가 차단될 수 있습니다