01 · Quickstart

빠른 시작 — end-to-end 예제

ADMap API 에 처음 연동하는 컨슈머가 연결 확인부터 응답 처리까지 한 번에 따라가는 예제다. <BASE> 는 개요의 baseURL 표로 치환한다.

1. 연결 · 버전 확인

인증 없이 서버 생존과 릴리즈 버전을 확인한다. 컨슈머는 자기 쪽 호환 버전 체크에 이 값을 쓴다.

curl -s -i <BASE>/api/health/version
# → 200
# { "version": "0.1.1", "releasedAt": "2026-06-16T00:00:00.000Z" }

releasedAt 은 릴리즈 타임스탬프가 없으면 null 이다. version 만으로 분기한다.

2. 에러 처리 규약

현재 문서화된 health/version seed 와 신규 문서화 엔드포인트는 { "error": "<code>" } 봉투를 기준으로 시작한다. Public v1 legacy/brand 경로는 { "error_code": "<code>" } 를 쓰는 계약도 있으므로, 실제 분기 필드는 API 레퍼런스의 엔드포인트별 스키마를 따른다.

async function call(path: string, init?: RequestInit) {
const res = await fetch(`${BASE}${path}`, init);
const body = await res.json();
if (!res.ok) {
  // Documented seed endpoints: { error: string }
  // Some public v1 endpoints: { error_code: string }
  throw new Error(`${res.status} ${body.error ?? body.error_code}`);
}
return body;
}

레이트 리밋(60초/100요청) 초과 시 429 로 내려온다. 응답 필드는 엔드포인트별 계약을 확인하고, 재시도는 백오프를 둔다.

다음 단계

도메인별 엔드포인트(미디어 분석 등)의 요청/응답 스키마는 API 레퍼런스 (/docs) 에서 확인한다. 도메인 연동 가이드는 순차적으로 이 가이드에 추가된다.