ApiCook이란

공개 API를 그대로 쓰기 어려운 이유와, ApiCook이 그 문제를 어떻게 다루는지 설명합니다.

공개 API는 무료로 열려 있지만, 프론트엔드에서 그대로 쓰기는 어렵습니다. ApiCook은 그 사이의 마찰을 줄이는 도구입니다.

공개 API를 그대로 쓰기 어려운 이유

공공데이터포털에서 대기질 측정 API를 하나 골랐다고 해봅시다. 문서를 읽고, 인증키를 발급받고, 브라우저에서 호출해보면 대개 이런 문제를 순서대로 만나게 됩니다.

첫째, 응답이 깊고 장황합니다. 실제 데이터는 이런 껍데기 안에 들어 있습니다.

{
  "response": {
    "header": { "resultCode": "00", "resultMsg": "NORMAL_SERVICE" },
    "body": {
      "items": {
        "item": [
          { "stationName": "종로구", "pm10Value": "45", "pm25Value": "23", "dataTime": "2026-08-28 14:00" }
        ]
      },
      "numOfRows": 10, "pageNo": 1, "totalCount": 1
    }
  }
}

필요한 건 stationName과 pm10Value 둘뿐인데 response.body.items.item까지 네 단계를 내려가야 합니다. 화면 코드마다 이 경로가 반복되고, 기관이 응답 구조를 바꾸면 그 코드가 전부 깨집니다.

둘째, 타입이 전부 문자열입니다. 위 응답의 pm10Value는 숫자 45가 아니라 문자열 "45"입니다. 정렬하면 "100"이 "45"보다 앞에 오고, 그래프를 그리면 축이 뒤엉킵니다. 받는 쪽에서 매번 Number()로 감싸야 합니다.

셋째, 브라우저에서 직접 호출하면 CORS에 막힙니다. 대부분의 공개 API는 Access-Control-Allow-Origin 헤더를 주지 않습니다. 서버가 응답을 보내도 브라우저가 자바스크립트에 넘겨주지 않습니다. 그래서 API를 호출하기 위한 서버를 따로 세우게 됩니다.

넷째, 인증키가 코드에 노출됩니다. 공개 API는 대개 인증키를 쿼리 파라미터로 받습니다. 브라우저에서 호출하면 네트워크 탭에 그대로 찍히고, 번들에 문자열로 남습니다.

ApiCook이 하는 일

ApiCook은 이 네 가지를 가공 규칙과 SDK로 나눠 처리합니다.

가공 규칙은 "응답의 어디를 읽고, 무엇을 걸러내고, 어떤 이름과 타입으로 내보낼지"를 정의한 설정입니다. 웹 에디터에서 실제 응답을 보면서 클릭으로 만들고, 저장하면 프로젝트 설정 JSON에 담깁니다.

SDK는 그 설정을 내려받아 적용합니다. 호출하는 쪽 코드는 이렇게 됩니다.

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

const cook = new ApiCook('your-project-id', { apiKey: 'apk_...' });

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

경로 탐색도, 타입 변환도 호출부에 없습니다. 응답 구조가 바뀌면 에디터에서 규칙만 고치면 되고, 이미 배포된 앱은 코드 수정 없이 새 규칙을 따라갑니다.

CORS와 인증키는 동작 모드로 해결합니다. 브라우저에서는 SDK가 자동으로 프록시 모드가 되어 ApiCook 서버를 경유하고, 서버 환경에서는 원본 API를 직접 호출합니다. 자세한 내용은 direct 모드와 proxy 모드에서 다룹니다.

ApiCook이 하지 않는 일

오해를 줄이기 위해 경계를 분명히 해둡니다.

데이터를 저장하지 않습니다. ApiCook은 원본 API의 응답을 그때그때 가져와 가공해 넘길 뿐, 데이터베이스에 쌓아두지 않습니다. 짧은 캐시는 있지만 그건 성능을 위한 것입니다(캐시 동작 참고).
백엔드를 대체하지 않습니다. 인증·권한·비즈니스 로직이 필요한 일은 여전히 여러분의 서버가 해야 합니다. ApiCook이 줄여주는 건 "외부 API를 호출해 모양을 다듬는" 그 한 층입니다.
원본 API의 가용성을 보장하지 않습니다. 원본이 죽으면 호출도 실패합니다. 다만 자료실의 각 API가 지금 살아 있는지는 ApiCook이 주기적으로 점검해 기록하고 있습니다.

지원 범위: JSON 응답

ApiCook은 JSON 응답만 가공할 수 있습니다. 원본 API가 XML이나 CSV를 반환하면 direct 모드에서는 응답 파싱 단계에서, proxy 모드에서는 지원하지 않는 응답 형식 오류로 실패합니다.

자료실에 등록된 5,939개 API 중 JSON을 반환하는 것은 5,156개이고, XML만 반환하는 API가 325개입니다. 자료실 상세 페이지의 응답 형식 항목에서 미리 확인할 수 있습니다. 같은 기관의 서비스라도 엔드포인트별로 형식이 다른 경우가 있으니, JSON 응답을 지원하는지 원본 문서에서 함께 확인하는 편이 안전합니다.

다음 단계

5분 시작 가이드 — 프로젝트를 만들고 첫 응답을 받아봅니다.
핵심 개념 — 프로젝트·엔드포인트·가공 규칙이 어떤 관계인지 정리합니다.