5분 시작 가이드

프로젝트 생성부터 SDK로 첫 응답을 받기까지의 전 과정을 순서대로 따라갑니다.

프로젝트를 만들고 SDK로 첫 응답을 받기까지, 실제 순서대로 따라갑니다. 준비물은 ApiCook 계정과 Node.js 18 이상입니다.

1. 프로젝트 만들기

로그인 후 대시보드 > 프로젝트에서 새 프로젝트를 만듭니다. 프로젝트는 가공 규칙과 SDK 키를 담는 단위입니다. 앱 하나에 프로젝트 하나가 보통이고, 스테이징과 프로덕션을 나누고 싶다면 둘로 만들면 됩니다.

2. 쓸 API 고르기

자료실에서 원하는 API를 찾습니다. 검색은 이름뿐 아니라 설명까지 훑으므로 "대기질", "버스 도착" 같은 일상어로 찾아도 됩니다.

고르기 전에 상세 페이지에서 두 가지를 확인하세요.

응답 형식이 JSON인지. ApiCook은 JSON만 가공합니다. XML만 반환하는 API는 지금 단계에서 걸러야 나중에 헛수고를 피합니다.
최근 가동 상태. ApiCook이 주기적으로 점검한 결과가 상세 페이지에 있습니다. 오랫동안 응답하지 않는 API라면 규칙을 다 만들어도 데이터를 받을 수 없습니다.

API를 정했으면 상세 페이지에서 프로젝트에 추가를 누릅니다.

3. 인증키 준비하기

대부분의 공개 API는 기관에서 발급한 인증키를 요구합니다. 공공데이터포털이라면 해당 서비스의 활용 신청을 하고 발급받은 일반 인증키(Encoding/Decoding 두 가지가 나오는데, 쿼리 파라미터로 붙일 때는 보통 Decoding 키를 씁니다)를 준비합니다.

승인까지 시간이 걸리는 API가 있습니다. 자동 승인이면 몇 분, 심의가 필요하면 하루 이상 걸리기도 합니다. 인증키가 없으면 다음 단계의 미리보기에서 인증 오류만 보게 됩니다.

4. 가공 규칙 만들기

에디터에서 엔드포인트를 고르고 인증키를 넣어 미리보기를 실행하면 원본 응답이 트리로 펼쳐집니다. 여기서 규칙을 만듭니다.

데이터 위치 지정 — 실제 목록이 들어 있는 경로를 고릅니다. 공공데이터포털이라면 대개 response.body.items.item입니다.
필드 선택과 이름 바꾸기 — 필요한 필드만 고르고 출력 이름을 정합니다. pm10Value를 pm10으로, stationName을 station으로 바꾸는 식입니다.
타입 변환 — 문자열로 오는 숫자에 toNumber를 겁니다. 이걸 해두면 받는 쪽에서 매번 변환할 일이 없습니다.

미리보기 패널이 규칙 적용 전후를 나란히 보여주므로, 원하는 모양이 나올 때까지 조정하면 됩니다. 규칙의 자세한 동작은 가공 규칙 이해하기에 있습니다.

5. slug 정하고 배포하기

slug는 SDK에서 이 엔드포인트를 부를 이름입니다. air-quality처럼 소문자와 하이픈으로 짓습니다. 코드에 그대로 등장하므로 나중에 알아볼 수 있는 이름이 좋습니다.

그다음 SDK API 키 생성을 누릅니다. apk_로 시작하는 키가 나오는데, 이 화면에서만 원문을 볼 수 있습니다. 서버는 해시만 저장하므로 나중에 다시 확인할 수 없고, 잃어버리면 재발급해야 합니다. 지금 복사해서 안전한 곳에 두세요.

키가 있어야 배포하기가 활성화됩니다. 배포하면 규칙이 설정 JSON으로 내보내지고, 그때부터 SDK가 그 규칙을 내려받을 수 있습니다. 배포하지 않은 규칙은 SDK에 반영되지 않습니다 — 에디터에서 미리보기가 잘 나왔는데 SDK에서 엔드포인트를 못 찾는다면 대개 이 단계를 빠뜨린 경우입니다.

6. SDK로 호출하기

npm install @apicook/sdk

import { ApiCook } from '@apicook/sdk';

const cook = new ApiCook('your-project-id', {
    apiKey: process.env.APICOOK_API_KEY!,
});

// 인증키는 한 번만 설정해두면 이후 호출에 자동으로 실립니다
cook.setAuth('air-quality', { serviceKey: process.env.DATA_GO_KR_KEY! });

const stations = await cook.fetch('air-quality', { sidoName: '서울' });
console.log(stations);
// [{ station: '종로구', pm10: 45, measuredAt: '2026-08-28 14:00' }, ...]

your-project-id는 프로젝트 설정에서 확인할 수 있습니다.

원본 API의 인증키(serviceKey)와 ApiCook의 SDK 키(apiKey)는 다른 것입니다. 전자는 데이터를 주는 기관이 발급한 것이고, 후자는 여러분의 가공 규칙에 접근하기 위한 것입니다. 둘 다 환경변수로 관리하세요.

브라우저에서 쓴다면

위 코드를 그대로 브라우저에서 실행해도 동작합니다. SDK가 실행 환경을 감지해 프록시 모드로 전환하므로 CORS에 막히지 않습니다.

다만 브라우저 번들에 들어간 SDK 키는 공개된 것으로 봐야 합니다. 프로젝트 설정에서 허용 도메인을 지정해 다른 사이트에서 그 키를 쓰지 못하게 막는 것이 함께 필요합니다. 자세한 내용은 보안에서 다룹니다.

잘 안 될 때

엔드포인트 'xxx'를 찾을 수 없습니다 — 배포를 하지 않았거나 slug가 다릅니다. cook.endpoints로 실제 목록을 확인해보세요.
유효하지 않은 API 키입니다 — SDK 키가 잘못됐거나 다른 프로젝트의 키입니다.
응답은 오는데 값이 null — 데이터 위치(sourceRoot)가 실제 응답 구조와 어긋난 경우입니다.

더 많은 사례는 문제 해결에 정리해 두었습니다.