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