핵심 개념

ApiCook에는 이름이 비슷한 개념이 몇 개 있습니다. 한 번 정리해두면 에디터 화면과 SDK 코드가 어떻게 이어지는지 보입니다.

프로젝트

가공 규칙과 SDK 키를 담는 최상위 단위입니다. SDK 생성자의 첫 인자가 프로젝트 ID입니다.

const cook = new ApiCook('프로젝트-ID', { apiKey: 'apk_...' });

한 프로젝트의 SDK 키로는 그 프로젝트의 엔드포인트만 호출할 수 있습니다. 스테이징과 프로덕션에서 다른 규칙을 쓰고 싶다면 프로젝트를 나누는 것이 가장 단순한 방법입니다.

자료실 API와 엔드포인트

자료실 API는 기관이 제공하는 서비스 하나입니다. 예를 들어 "한국환경공단 대기오염정보 조회 서비스"가 API 하나입니다.

그 안에 엔드포인트가 여러 개 있습니다. 측정소별 조회, 시도별 조회, 통계 조회처럼 실제 호출 경로들이죠. 자료실 상세 페이지의 엔드포인트 목록에서 각각의 파라미터와 응답 구조를 볼 수 있습니다.

여기까지는 ApiCook이 수집해둔 읽기 전용 정보입니다. 아직 여러분의 것이 아닙니다.

가공 엔드포인트와 slug

자료실 API를 프로젝트에 추가하면, 그때부터 가공 엔드포인트를 만들 수 있습니다. 이것이 여러분이 실제로 호출할 단위입니다.

가공 엔드포인트에는 세 가지가 붙습니다.

• slug — SDK에서 부를 이름. cook.fetch('air-quality')의 그 문자열입니다.
• 가공 규칙 — 응답의 어디를 읽고 어떤 모양으로 내보낼지.
• 소스 — 실제로 호출할 원본 엔드포인트. 보통 하나지만, Pro 플랜에서는 여러 개를 붙여 병렬 호출할 수 있습니다(병렬 멀티소스 호출).

즉 slug 하나가 SDK 호출 하나이고, 그 뒤에 원본 API 호출이 하나 또는 여럿 있는 구조입니다.

배포

에디터에서 규칙을 저장하는 것과, 그 규칙이 SDK에 반영되는 것은 별개입니다.

저장은 작업 내용을 보관할 뿐이고, 배포를 해야 규칙이 설정 JSON으로 내보내집니다. SDK는 그 JSON을 내려받아 동작하므로, 배포하지 않은 규칙은 SDK 입장에서 존재하지 않습니다.

이 분리 덕분에 규칙을 마음껏 고치다가 완성됐을 때만 반영할 수 있습니다. 반대로 "에디터에서는 잘 되는데 SDK에서 엔드포인트를 못 찾는" 상황의 대부분은 배포를 빠뜨린 경우입니다.

설정 JSON

배포하면 만들어지는 산출물입니다. 프로젝트의 모든 엔드포인트와 그 가공 규칙, 허용 도메인이 담겨 있고 다음 주소에서 서빙됩니다.

GET https://api.apicook.dev/api/v1/sdk/{projectId}.json
X-ApiCook-Key: apk_...

SDK가 처음 호출될 때 이 JSON을 받아 메모리에 캐시하고, 이후 호출은 캐시된 규칙으로 처리합니다. 기본 캐시 수명은 60초입니다(캐시 동작).

설정 JSON에는 HMAC 서명이 함께 실립니다. SDK는 direct 모드에서 이 서명을 검증해, 전송 중에 규칙이 바뀌지 않았는지 확인합니다.

두 가지 키

이름이 비슷해서 자주 헷갈리는 부분입니다.

	발급처	쓰임	어디에 두나
SDK API 키 (apk_...)	ApiCook	설정 JSON 조회, 프록시 호출 인증	서버 환경변수. 브라우저에서 쓴다면 허용 도메인 설정 필수
원본 API 인증키	데이터 제공 기관	원본 API 호출	서버 환경변수. 브라우저 노출 주의

SDK 코드에서는 각각 이렇게 나타납니다.

const cook = new ApiCook('project-id', {
    apiKey: process.env.APICOOK_API_KEY!,        // ← SDK API 키
});

cook.setAuth('air-quality', {
    serviceKey: process.env.DATA_GO_KR_KEY!,     // ← 원본 API 인증키
});

SDK 키는 발급 직후 한 번만 원문이 보이고, 서버에는 해시만 저장됩니다. 잃어버리면 재발급밖에 방법이 없고, 재발급하면 이전 키는 즉시 무효가 됩니다.

동작 모드

SDK는 실행 환경에 따라 두 가지로 동작합니다.

• direct — 원본 API를 직접 호출하고, 받은 응답에 가공 규칙을 SDK 안에서 적용합니다. 서버 환경의 기본값입니다.
• proxy — ApiCook 서버에 호출을 위임하고 가공된 결과만 받습니다. 브라우저의 기본값입니다.

브라우저는 CORS 때문에 대부분의 공개 API를 직접 호출할 수 없어서 proxy가 됩니다. 같은 코드가 환경에 따라 다르게 동작하는 셈인데, 그래서 direct 모드와 proxy 모드의 차이를 알아두는 편이 좋습니다.

전체 그림

자료실 API (읽기 전용, ApiCook이 수집)
   └─ 엔드포인트 (원본 호출 경로)
          ↓ 프로젝트에 추가
프로젝트
   └─ 가공 엔드포인트 = slug
          ├─ 가공 규칙
          └─ 소스 1..N (원본 엔드포인트를 가리킴)
          ↓ 배포
설정 JSON  ──(SDK가 내려받음)──▶  cook.fetch('slug')