핵심 개념
빠른 시작에서 등장한 용어들을 더 자세히 설명합니다.
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 호출 시 요청 헤더에 포함 | 협업자가 직접 처리 결과 수신 |
재시도 정책: 실패 시 최대 3회 재시도 (1~2초 백오프)
참고: 웹훅 재시도가 모두 실패해도 데이터는 안전하게 저장됩니다. 로그에서 웹훅 상태를 확인할 수 있습니다.
8. 이벤트 알림 (Discord / Slack / Telegram)
Discord, Slack, Telegram으로 주요 이벤트에 대한 즉시 알림을 받을 수 있습니다.
설정: 대시보드 → API → 엔드포인트 상세 → 알림 설정
지원하는 알림 항목:
- 웹훅 전달 실패 (본인 웹훅만)
- 월간 사용량 80% 경고 (소유자만)
- 월간 사용량 한도 초과 (소유자만)
- 새 배포 요청 (소유자만)
- 배포 완료 (협업자만)
참고: 알림은 best-effort 방식입니다. 전송 실패 시 재시도하지 않으며, 전송 이력은 저장되지 않습니다.
9. 데이터 아카이빙
프로덕션 데이터는 30일이 지나면 별도 저장소에 아카이브 파일로 백업됩니다.
환경별 정책:
| 환경 | 정책 | 비고 |
|---|---|---|
| 프로덕션 (유료 플랜) | 30일 이후 자동 아카이빙 | 30일 후 별도 저장소에 백업 파일 자동 생성, 다운로드 가능 |
| 샌드박스 (유료 플랜) | 30일 이후 자동 삭제 | 테스트 데이터, 아카이빙 없음 |
| Free 플랜 | 엔드포인트 생성 7일 후 전체 삭제 | 엔드포인트 단위 삭제 |
아카이브 다운로드:
- 위치: 대시보드 > 아카이브
- JSONL.gz: 시스템 필드를 포함한 전체 레코드 (원본 아카이브)
- CSV: 페이로드 필드만 추출, 재귀 평탄화 (최대 depth 5), 엑셀 호환 (UTF-8 BOM)
- 각 파일은 하루치 프로덕션 레코드를 포함합니다
- 유료 플랜에서만 사용 가능합니다