이 페이지에서 정하는 내용
이 페이지는 특정 API 메서드에 의존하지 않는 규칙을 모았습니다: 인증, 응답 버전, 오류 처리, 재시도, 테스트 API 사용, 출시 전 점검입니다.
메서드별 매개변수, 스키마, 예제는 API 레퍼런스를 사용하세요. 지원 범위와 메서드 그룹을 비교하려면 플랫폼 페이지를 사용하세요.
이 페이지를 새 연동을 위한 팀의 공통 기준으로 삼으세요. API 레퍼런스를 반복하지 않고 보완합니다.
API 문서
플랫폼 API 연동 규칙
API 키 전송, 응답 구조 선택, 첫 요청, 오류 처리, 테스트 데이터 검증을 정리한 간결한 연동 레퍼런스입니다.
인증
플랫폼 API에 보내는 모든 요청에서 `X-API-Key` 헤더에 API 키를 넣어 보내세요.
키는 대시보드 세션에서 상속되지 않습니다. 백엔드 서비스, 워커, 백그라운드 작업은 이 헤더를 명시적으로 보내야 합니다.
- 키는 비밀 저장소에 보관하고, 접근 권한이 바뀌거나 유출이 의심되면 교체하세요.
- 키를 브라우저 코드, 공개 저장소, 클라이언트 번들, 로그에 넣지 마세요.
- 가능하면 환경별, 서비스별로 키 접근을 제한하세요.
응답 구조 선택
V1과 V2는 같은 API 메서드 카탈로그를 제공하지만 반환하는 데이터 구조가 다릅니다. 클라이언트를 만들기 전에 버전을 선택하고 연동 설정에 고정하세요.
같은 처리 흐름에서 V1과 V2를 섞지 마세요. 매핑, 캐싱, 테스트, 유지보수가 복잡해집니다.
V1
원본 응답 V1
ScrapeStorm의 최소한의 변경만 거친 소스 플랫폼의 응답 형태를 유지합니다.
사용 시점
이전, 하위 호환성, 이미 플랫폼 고유 필드에 의존하는 클라이언트.
V2
정규화된 응답 V2
제품 코드, 분석, 내부 서비스를 위한 더 안정적인 데이터 계약을 제공합니다.
사용 시점
새 연동, 새 서비스, 소스 플랫폼의 데이터 형태가 필요 없는 모든 코드.
기본적으로 V2를 사용하세요. V1은 기존 클라이언트의 호환성이나 이전을 위해서만 유지하세요.
첫 실제 API 요청 보내기
버전을 선택한 후 실제 API 메서드로 연동을 확인하세요: 기본 URL, 헤더, 쿼리 매개변수, 시간 제한, 오류 처리입니다.
| HTTP 메서드 | GET |
|---|---|
| 엔드포인트 | /api/v2/youtube.com/profile/about-by-user-identifier |
| 쿼리 매개변수 예시 | user_identifier=mkbhd |
| 헤더 | X-API-Key |
이 예제는 YouTube API 메서드 `profile/about-by-user-identifier`를 사용합니다. `user_identifier`를 자신의 시나리오에 맞는 테스트 식별자로 바꾸세요.
성공 응답은 전송과 최상위 구조가 작동한다는 것만 증명합니다. 출시할 각 API 메서드를 한도, 요금, 오류 처리와 함께 검증하세요.
응답 형태 확인
V1과 V2의 공개 플랫폼 API 메서드는 같은 외부 봉투인 `success`, `status`, `data`를 사용합니다. 컬렉션 메서드는 최상위에 `pagination`을 포함할 수도 있습니다.
버전 선택으로 바뀌는 것은 `data` 내부의 스키마이며 전송 봉투가 아닙니다. 선택한 메서드의 정확한 필드는 API 레퍼런스에서 확인하세요.
| 응답 유형 | 최상위 필드 | 먼저 읽어야 할 것 |
|---|---|---|
| 성공 응답 |
success,
status,
data
|
`data`에 메서드 데이터가 들어 있습니다. |
| 페이지로 나뉜 성공 응답 |
success,
status,
pagination,
data
|
`pagination`은 최상위에 있고, 메서드 데이터는 `data`에 남아 있습니다. |
| 오류 응답 |
success,
status,
error,
meta
|
HTTP 상태와 `error.code`로 분기하세요. |
봉투에서 V1인지 V2인지 추측하지 마세요. URL과 클라이언트 설정에서 버전을 고정한 다음, 해당 버전의 레퍼런스에 따라 메서드 스키마를 해석하세요.
오류는 텍스트가 아닌 코드로 처리하세요
오류는 공통 봉투를 사용합니다. HTTP 상태와 `error.code`로 분기하세요. `message` 필드는 표시나 로깅용이며 애플리케이션 흐름 제어에 사용하지 마세요.
- `401`, `402`, `422`는 원인이 바뀌기 전까지 재시도하지 마세요.
- `429 RATE_LIMIT_EXCEEDED`는 `Retry-After` 또는 `error.retry_after_seconds` 이후에만 재시도하세요.
- `500`과 `503`은 제한된 백오프와 고정된 최대 시도 횟수로 재시도하세요.
| HTTP 상태 | 오류 코드 | 클라이언트 조치 |
|---|---|---|
| 401 |
인증되지 않음
UNAUTHORIZED
|
API 키와 환경을 확인하세요. 같은 키로 같은 요청을 반복해서 재시도하지 마세요. |
| 422 |
검증 실패
VALIDATION_FAILED
|
요청 매개변수를 수정하세요. 같은 입력은 같은 오류를 반환합니다. |
| 402 |
크레딧 부족
INSUFFICIENT_CREDITS
|
잔액이나 계정 한도가 업데이트될 때까지 흐름을 중지하세요. |
| 429 |
동시 연결 초과
CONCURRENT_CONNECTIONS_EXCEEDED
|
API 키당 병렬 작업을 줄이거나 요청을 대기열에 넣으세요. |
| 429 |
속도 제한 초과
RATE_LIMIT_EXCEEDED
|
안내된 재시도 간격을 기다리고 워커 간 재시도를 조율하세요. |
| 503 |
엔드포인트 사용 불가
ENDPOINT_UNAVAILABLE
|
다른 메서드가 작동한다면 전체 연동을 멈추지 말고 메서드 단위로 백오프를 적용하세요. |
| 500 |
내부 서버 오류
INTERNAL_SERVER_ERROR
|
제한된 백오프로 재시도하세요. 최대 시도 횟수에 도달하면 실패를 기록하고 모니터링을 통해 에스컬레이션하세요. |
`RATE_LIMIT_EXCEEDED`의 경우 다음 시도 시점에 대한 유일하게 신뢰할 수 있는 정보는 `Retry-After` 또는 `error.retry_after_seconds`입니다.
테스트 데이터로 형태 검증
테스트 API 메서드는 소스 플랫폼을 호출하지 않고 정적 JSON 예시를 반환합니다. 클라이언트, 화면, 파서 테스트 개발에 사용하세요.
테스트 API는 메서드 가용성, 데이터 최신성, 한도, 요금, 운영 환경 동작을 증명하지 않습니다. 출시 전에 같은 시나리오를 운영 API에서 다시 실행하세요.
- 데이터 최신성을 확인하는 데 테스트 데이터를 사용하지 마세요.
- 테스트 값을 운영 환경의 연동 로직에 옮기지 마세요.
- 봉투, 필드 이름, 응답의 기본 구조만 비교하세요.
| 테스트 API | https://www.scrapestorm.net/api-mock |
|---|---|
| 예시 | https://www.scrapestorm.net/api-mock/v2/youtube.com/profile/about-by-user-identifier?user_identifier=mkbhd |
| API 레퍼런스 |
운영 환경 체크리스트
실제 트래픽을 보내고 워커 병렬도를 높이기 전에 이 점검을 진행하세요.
-
01
응답 버전이 고정됨
새 클라이언트는 V2를 사용합니다. V1은 기존 연동의 호환성이나 이전을 위해서만 허용됩니다.
-
02
API 키가 비밀로 보관됨
키는 비밀 저장소에 있으며 프런트엔드 코드, 공개 저장소, 클라이언트 번들, 로그에 포함되지 않습니다.
-
03
오류 처리가 기계 판독 코드에 기반함
클라이언트 분기는 HTTP 상태와 `error.code`에 따릅니다. `message`는 비즈니스 로직에 사용하지 않습니다.
-
04
재시도가 제한됨
`RATE_LIMIT_EXCEEDED`는 `Retry-After` 또는 `error.retry_after_seconds`를 기다립니다. `402`와 `422`는 같은 입력으로 재시도하지 않습니다. `500`과 `503`에는 백오프와 시도 한도가 있습니다.
-
05
API 키별로 병렬도가 관리됨
대기열 또는 속도 제한기가 워커, cron 작업, 백그라운드 프로세스의 동시 요청을 제한합니다.
-
06
테스트와 운영을 별도로 검증함
테스트 데이터는 데이터 형태를 검증합니다. 운영 API는 실제 매개변수, 한도, 가용성, 크레딧 사용량을 검증합니다.
-
07
API 메서드 요금이 확인됨
트래픽이 늘어나기 전에 사용할 API 메서드의 비용을 확인하세요.
API 레퍼런스와 플랫폼
각 메서드의 구체적인 매개변수, 스키마, 예제는 필요한 버전의 API 레퍼런스를 여세요. 소스와 메서드 그룹을 선택하려면 플랫폼을 사용하세요.