엔드포인트 호출

fetch()는 SDK의 거의 전부입니다. slug를 주면 가공된 결과가 돌아옵니다.

기본 호출

const data = await cook.fetch('air-quality', { sidoName: '서울' });

첫 인자는 배포된 엔드포인트의 slug, 둘째는 원본 API에 전달할 파라미터입니다. 파라미터가 없으면 생략할 수 있습니다.

const all = await cook.fetch('notices');

파라미터가 어디로 가는가

두 번째 인자의 값들은 원본 API 호출 URL로 들어갑니다. 배치는 엔드포인트에 정의된 파라미터 위치를 따릅니다.

• query 파라미터 — 쿼리 문자열에 붙습니다. 기본 동작입니다.
• path 파라미터 — 경로의 {name} 자리에 치환되고, 값은 URL 인코딩됩니다.

// path: /stations/{stationId}/measurements
await cook.fetch('measurements', { stationId: '종로구', hours: '24' });
// → /stations/%EC%A2%85%EB%A1%9C%EA%B5%AC/measurements?hours=24

엔드포인트에 정의되지 않은 파라미터도 쿼리에 그대로 실립니다. 문서에 없는 옵션을 시험해볼 때는 편하지만, 오타 난 파라미터 이름이 조용히 전달되어 원본 API가 무시하는 상황도 같이 생깁니다. 결과가 기대와 다르면 파라미터 이름부터 확인하세요.

파라미터 정의에 header 위치가 있더라도 SDK는 이를 쿼리 파라미터로 전달합니다. 헤더로 인증하는 API는 현재 SDK의 파라미터 경로로는 처리할 수 없습니다.

POST 등 본문이 필요한 호출

세 번째 인자로 body를 넘깁니다.

const result = await cook.fetch('submit', {}, { body: { name: 'test', count: 3 } });

Content-Type: application/json이 자동으로 붙고 본문은 JSON 문자열로 직렬화됩니다. 엔드포인트의 메서드가 GET이면 body는 무시됩니다 — GET에 본문을 실을 수 없기 때문입니다.

반환 타입

기본 반환 타입은 unknown입니다. 제네릭으로 지정하면 이후 코드에서 자동완성이 동작합니다.

interface Station {
    station: string;
    pm10: number;
    measuredAt: string;
}

const stations = await cook.fetch<Station[]>('air-quality', { sidoName: '서울' });
stations[0].pm10;  // number

이 타입은 컴파일 시점의 약속일 뿐 런타임 검증이 아닙니다. 원본 API가 다른 모양을 보내면 타입과 실제 값이 어긋납니다. 자세한 내용은 TypeScript 타입에 있습니다.

사용 가능한 slug 확인하기

console.log(cook.endpoints);
// ['air-quality', 'bus-arrival', 'notices']

주의: 이 값은 설정 JSON을 내려받은 뒤에야 채워집니다. direct 모드에서는 첫 fetch()가 설정을 로드하므로 그 이후에 값이 보이고, proxy 모드는 설정을 아예 내려받지 않으므로 항상 빈 배열입니다.

proxy 모드에서 목록을 보고 싶다면 refresh()를 먼저 부르세요.

await cook.refresh();
console.log(cook.endpoints);

이 제약 때문에, 존재하지 않는 slug를 호출했을 때의 에러 메시지도 모드에 따라 다릅니다. direct 모드는 사용 가능한 목록을 함께 알려주지만 proxy 모드는 서버가 판단해 응답합니다.

설정 강제 갱신

await cook.refresh();

캐시를 버리고 설정 JSON을 즉시 다시 받습니다. 규칙을 배포한 직후 반영을 기다리기 싫을 때 씁니다.

장시간 떠 있는 프로세스에서는 자동 갱신(기본 60초)에 맡기면 되고, refresh()를 매 호출마다 부르면 캐시가 무의미해집니다.

멀티소스 엔드포인트

소스를 여러 개 붙인 엔드포인트는 파라미터를 소스 라벨로 감싸서 전달합니다.

const data = await cook.fetch('dashboard', {
    weather: { city: '서울' },
    news: { q: '날씨' },
});

평면으로 넘기면 어느 소스로 보낼지 알 수 없어 무시됩니다. 반대로 단일 소스 엔드포인트는 평면 파라미터를 받습니다. 자세한 구조는 병렬 멀티소스 호출에서 다룹니다.