사용 규칙
페이지네이션
목록 조회는 기간 상한과 커서 두 가지로 크기를 제한합니다.
기간 상한
한 번의 조회는 최대 31일입니다. 정확히는 to − from ≤ 30일이며,
양끝을 포함해 31일입니다. 달력상 한 달은 항상 조회할 수 있습니다.
허용
?from=2026-08-01&to=2026-08-31 ← 31일. OK
?from=2026-08-01&to=2026-09-01 ← 32일. 400 range_too_largei
더 긴 기간이 필요하다면
월 단위로 나누어 호출하고 결과를 합치세요. 기간 상한은 성능 보호 장치이며 완화되지 않습니다.
커서
응답의 next_cursor 를 다음 요청의 cursor 파라미터에 그대로 넣습니다. has_more 가 false 이거나 next_cursor 가 null 이면 끝입니다.
응답
{
"data": [ /* ... */ ],
"next_cursor": "eyJ0IjoiMjAyNi0wOC0xNCIsImkiOiJhcl8zRmQ4In0",
"has_more": true
}limit기본 100, 최대 1000.- 커서는 불투명 문자열입니다. 디코딩하거나 직접 만들지 마세요.
- 커서에는 조회 조건이 담겨 있습니다.
cursor를 넘길 때 다른 파라미터를 바꾸면400 invalid_cursor입니다. - offset·page 번호 방식은 지원하지 않습니다.
전체 순회
async function* pages(path, params, token) {
let cursor = null;
do {
const qs = new URLSearchParams({ ...params, limit: "500" });
if (cursor) qs.set("cursor", cursor);
const res = await fetch(`https://developer.openapi.giig.app/api/v1${path}?${qs}`, {
headers: { Authorization: `Bearer ${token}` }
});
if (res.status === 429) {
// Retry-After 를 존중한다. 즉시 재시도하면 잠길 수 있다.
await new Promise(r => setTimeout(r, Number(res.headers.get("Retry-After") ?? 5) * 1000));
continue;
}
if (!res.ok) throw new Error((await res.json()).error.code);
const body = await res.json();
yield body.data;
cursor = body.next_cursor;
} while (cursor);
}규칙
- 정렬은 서버가 정합니다. 정렬 파라미터는 없습니다.
- 같은 커서로 두 번 요청하면 같은 결과가 옵니다.
- 순회 도중 데이터가 바뀌면 마지막 페이지에서 일부가 어긋날 수 있습니다. 정합성이 중요하면 순회 후 증분 조회로 보정하세요.