핵심 개념
빠른 시작에서 등장한 용어들을 더 자세히 설명합니다.
1. API
데이터를 주고받는 통신 규격입니다. 프로그램 간 연결 통로라고 생각하세요.
3Min API에서는:
- 백엔드 코드 없이 API를 생성할 수 있습니다
- 표준 JSON 형식의 데이터를 수신합니다
- 수신된 데이터는 자동으로 저장되고, 웹훅으로 전달할 수 있습니다
2. 엔드포인트
데이터를 받는 API 주소입니다. 하나의 API = 하나의 엔드포인트.
각 엔드포인트는 다음을 포함합니다:
- 고유한 URL 경로 (자동 생성)
- 필수 필드 설정 (선택)
- 샌드박스/프로덕션 환경 분리
- 환경별 API 키 (
tm_test_xxx...,tm_live_xxx...)
3. JSON
3Min API는 표준 JSON 형식의 데이터를 수신합니다.
지원하는 필드 타입:
| string | 문자열 | Example |
|---|---|---|
| string | 문자열 | "hello" |
| number | 숫자 | 123, 45.67 |
| boolean | 참/거짓 | true, false |
| array | 배열 | [1, 2, 3] |
| object | 객체 | {"key": "value"} |
예시 (주문 정보):
{
"order_id": "ORD-2024-001",
"amount": 45000,
"items": ["Item A", "Item B"],
"paid": true,
"customer": {
"name": "John Doe",
"phone": "010-1234-5678"
}
}4. 필수 필드 (선택 설정)
필수 필드를 정의하지 않아도 표준 JSON은 모두 수용됩니다.
JSON 데이터에서 반드시 포함되어야 할 필드를 지정할 수 있습니다.
필수 필드를 정의하면:
- 해당 필드가 없는 요청은 거부됩니다 (400 에러)
- 데이터 품질을 보장할 수 있습니다
5. 샌드박스 vs 프로덕션
| 환경 | API 키 | 용도 |
|---|---|---|
| 샌드박스 | tm_test_xxx... | 개발 및 테스트 |
| 프로덕션 | tm_live_xxx... | 실서비스 운영 |
- API 키 접두사로 환경이 자동 결정됩니다
- 환경별로 웹훅을 따로 설정할 수 있습니다
- 샌드박스에서 충분히 테스트 후 프로덕션에 배포하세요
6. API 키
엔드포인트 호출 시 인증에 사용하는 키입니다. 소유자의 기본 API 키는 엔드포인트 생성 시 자동 발급되며 삭제할 수 없습니다. 키가 노출된 경우 재생성할 수 있습니다.
| API 키 | 환경 | 용도 |
|---|---|---|
tm_test_xxx... | 샌드박스 | 테스트용, 실서비스에 영향 없음 |
tm_live_xxx... | 프로덕션 | 실서비스용, 실제 데이터 처리 |
API 키가 노출되면 즉시 재생성하세요.
협업 키
협업 키를 만들고 협업자를 초대하면, 협업 키별로 로그와 통계를 분리하여 관리할 수 있습니다.
협업 키별로 로그를 필터링하여 사용량을 추적할 수 있습니다.
협업 키별로 허용할 작업(POST/GET/PUT/DELETE)을 환경별로 독립 설정할 수 있습니다. 읽기(GET) 권한은 단건·목록·검색 조회 모두에 적용됩니다.
7. 웹훅
데이터 도착 시 지정한 URL로 자동 알림을 보내는 기능입니다.
두 종류의 웹훅:
| 웹훅 | 설정 위치 | 설명 |
|---|---|---|
| 내 웹훅 | 대시보드 → API → 엔드포인트 상세 | 모든 API 호출 알림을 수신 |
| 협업자 웹훅 | API 호출 시 요청 헤더에 포함 | 협업자가 직접 처리 결과 수신 |
재시도 정책: 15초 안에 2xx 반환. 실패 시 큐에서 시간 단위로 재시도
참고: 웹훅 재시도가 모두 실패해도 데이터는 안전하게 저장됩니다. 로그에서 웹훅 상태를 확인할 수 있습니다.
8. 폴링
데이터를 받는 또 하나의 방법입니다. 저희가 여러분의 URL로 보내는 대신, 여러분의 클라이언트가 폴링 엔드포인트를 주기적으로 호출해 지난 호출 이후 들어온 것만 받아 갑니다.
웹훅과 폴링 비교:
| 항목 | 웹훅 (푸시) | 폴링 (풀) |
|---|---|---|
| 누가 호출하나 | 3Min API가 여러분을 호출합니다 | 여러분의 클라이언트가 저희를 호출합니다 |
| 필요한 것 | 15초 안에 응답하는 공개 URL | 들어오는 연결은 필요 없고, 나가는 HTTPS만 있으면 됩니다 |
| 지연 | 레코드가 저장된 뒤 수 초 | 폴링 주기에 약 60초의 안정화 지연이 더해집니다 |
| 비용 | 무료 — 배달은 API 호출로 집계되지 않습니다 | 폴링 요청 1건당 API 호출 1건. 빈 응답도 포함됩니다 |
받는 쪽에 공개 URL이 있고 데이터가 들어오는 즉시 반응해야 한다면 웹훅을 쓰세요. 기본 선택입니다.
공개 URL이 없다면 — 로컬 개발, 사내망, 방화벽 안쪽, 상시 실행 서버가 없는 경우 — 또는 받는 쪽이 속도를 스스로 조절해야 한다면 폴링을 쓰세요.
둘은 배타적이지 않습니다. 같은 엔드포인트에 둘 다 켜 둘 수 있어요. 실시간 반응은 웹훅으로, 놓친 것은 야간 폴링으로 메우는 식입니다.
요청 예시:
# First call - since a point in time
GET /api/v1/data/my-endpoint/poll?since=2026-09-01
Authorization: Bearer tm_test_xxx
# Response - oldest first
{
"success": true,
"data": [ ... ],
"pagination": {
"limit": 100,
"poll_cursor": "eyJ0IjoiMjAyNi0wOS0wMVQwMDowMDowMFoifQ"
}
}
# Next call - send the cursor back
GET /api/v1/data/my-endpoint/poll?cursor=eyJ0IjoiMjAyNi0wOS0wMVQwMDowMDowMFoifQ커서가 동작하는 방식:
- 첫 호출에는 since(RFC 3339 또는 YYYY-MM-DD, 항상 UTC로 해석)를 주거나 아무것도 주지 않습니다. 아무것도 주지 않으면 그 시점부터 구독합니다. since와 cursor는 함께 보낼 수 없습니다.
- next_cursor는 아직 남은 백로그가 있다는 뜻입니다 — 곧바로 다시 호출하세요
- poll_cursor는 따라잡았다는 뜻입니다 — 저장해 두고 다음 주기까지 기다리세요
- 레코드는 오래된 것부터 오며 한 번에 최대 100건입니다(limit, 1-100). 응답에는 두 커서 중 정확히 하나만 담깁니다
최근 60초 남짓은 큐가 따라잡는 동안 보류됩니다. 건너뛰는 게 아니라 다음 폴링으로 미뤄지는 것입니다. 재시도나 재기동으로 같은 레코드가 다시 올 수 있으니 레코드 id 기준으로 멱등하게 처리하세요.
9. 데이터 보관
레코드는 한정된 기간만 보관됩니다. 데이터가 3Min API 밖으로 나가는 경로는 대시보드가 아니라 웹훅 또는 폴링 엔드포인트라고 생각해 주세요.
환경별 정책:
| 환경 | 정책 | 비고 |
|---|---|---|
| 프로덕션 (유료 플랜) | 최소 60일 보관 | 보관 기간이 지나면 월 단위로 한꺼번에 삭제됩니다 |
| 샌드박스 (유료 플랜) | 30일 이후 자동 삭제 | 테스트용이며 저장소가 아닙니다 |
| Free 플랜 | 엔드포인트 생성 7일 후 전체 삭제 | 엔드포인트 단위 삭제 |
데이터를 내보내는 방법:
- 웹훅: 레코드가 들어오는 즉시 지정한 URL로 전달됩니다
- 폴링: 지난 호출 이후 들어온 것을 직접 가져옵니다 — 위 8번 항목 참조
- 로그: 보관 기간 안에는 대시보드에서 개별 레코드를 조회·검색할 수 있습니다
- 사용량 통계는 별도로 보관되어 레코드가 삭제돼도 남습니다. 대시보드 그래프는 그대로예요