REST API 개요 및 아키텍처

SmallPict REST API는 OpenAPI 3.1 표준을 준수하는 웹 서비스로, 개발자가 분산 이미지 최적화, 포맷 변환 및 글로벌 에지 CDN 파이프라인에 직접 접근할 수 있도록 설계되었습니다.

엔드포인트 기본 URL (Base URLs)

핵심 API 엔드포인트 안내

모든 엔드포인트는 HMAC-SHA256 인증 헤더를 필수로 요구합니다 (자세한 내용은 인증 가이드 참조).

1. 이미지 최적화 및 포맷 변환

• 엔드포인트: POST /v1/optimize (별칭: POST /v1/convert)
• 설명: 이미지 메타데이터 또는 바이너리를 제출하여 압축 및 포맷 변환(AVIF, WebP, JPEG, PNG)을 실행합니다.

2. 비동기 작업 상태 조회

• 엔드포인트: GET /v1/optimize/status?job_id={job_id}
• 설명: 대용량 비동기 이미지 변환 작업의 진행률, 용량 절감률 및 최종 CDN 다운로드 URL을 확인합니다.

3. 계정 쿼터 및 실시간 사용량

• 엔드포인트: GET /v1/quota
• 설명: 현재 월간 처리 바이트 수, 플랜 한도 및 CDN 에지 대역폭 소비량을 실시간 조회합니다.

4. 글로벌 CDN 에지 캐시 퍼지

• 엔드포인트: POST /v1/purge
• 설명: 전 세계 300개 이상의 SmallPict Edge 노드에서 지정된 이미지 자산의 캐시를 즉시 무효화합니다.

요청 및 응답 규격

• 모든 요청 페이로드는 application/json 포맷을 기본으로 합니다 (직접 바이너리 전송 시 multipart/form-data).
• 모든 응답 바디는 RFC3339 국제 표준 타임스탬프를 포함하는 정형화된 JSON을 반환합니다.
• 상태를 변경하는 모든 요청(POST, DELETE, PATCH)은 Idempotency-Key (UUID v4) 멱등성 헤더를 지원하여 네트워크 재시도 시에도 중복 과금이 발생하지 않습니다.