페이지네이션 가이드

목록 조회 API에서 사용하는 limit/offset 기반 페이지네이션 방식과 실제 응답 구조를 안내합니다.

개요

Book Print API 목록 조회는 offset 기반 페이지네이션을 사용합니다.limit(조회 수)과 offset(시작 위치) 쿼리 파라미터로 범위를 지정하며, 응답 본문의 pagination.hasNext 필드로 다음 페이지 존재 여부를 확인합니다.

Query 파라미터

경계 값 위반 시 400 응답

응답 본문에 fieldErrors 배열이 포함되며 각 항목은 { field, message } 구조입니다. 에러 응답 공통 규칙은 API 공통 사항을 참고하세요.

응답 구조

모든 list 엔드포인트는 data 자체가 항목 배열이고, 페이지네이션 메타는 최상위 pagination 형제 필드로 반환됩니다. 모든 엔드포인트가 동일한 envelope 구조를 사용하므로 클라이언트는 리소스명에 의존하지 않고 일관된 코드로 처리할 수 있습니다.

{
  "success": true,
  "message": "성공",
  "data": [ /* ... book 항목들 */ ],
  "pagination": {
    "total": 0,
    "limit": 10,
    "offset": 0,
    "hasNext": false
  }
}

{
  "success": true,
  "message": "성공",
  "data": [ /* ... order 항목들 */ ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "hasNext": true
  }
}

{
  "success": true,
  "message": "성공",
  "data": [ /* ... template 항목들 */ ],
  "pagination": {
    "total": 120,
    "limit": 100,
    "offset": 0,
    "hasNext": true
  }
}

사용 예시

첫 번째 페이지 조회

limit=20과 offset=0으로 첫 번째 페이지를 요청합니다.

curl 'https://api-sandbox.sweetbook.com/v1/orders?limit=20&offset=0' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

두 번째 페이지 조회

offset을 limit만큼 증가시켜 다음 페이지를 요청합니다.

curl 'https://api-sandbox.sweetbook.com/v1/orders?limit=20&offset=20' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

전체 목록 순회 (JavaScript)

pagination.hasNext가 false가 될 때까지 반복하며 항목을 수집합니다. 모든 list 엔드포인트가 동일한 envelope을 사용하므로 리소스명에 관계없이 같은 패턴이 적용됩니다.

async function fetchAllOrders(apiKey) {
  const allOrders = [];
  let offset = 0;
  const limit = 50;

  while (true) {
    const response = await fetch(
      `https://api-sandbox.sweetbook.com/v1/orders?limit=${limit}&offset=${offset}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    const json = await response.json();

    // 모든 list 응답에서 data 자체가 배열, pagination은 최상위
    allOrders.push(...json.data);

    if (!json.pagination?.hasNext) break;
    offset += limit;
  }

  return allOrders;
}

Best Practices

• limit 값은 용도에 맞게 조절하세요. UI 표시에는 20~50, 대량 동기화에는 100을 고려할 수 있습니다. 허용 범위는 1~100입니다.
• 큰 offset 값은 피하세요. offset이 클수록 데이터베이스 스캔 범위가 증가해 응답이 느려질 수 있습니다. 수천 건 이상 조회가 필요하면 createdFrom/createdTo 같은 날짜 필터로 범위를 좁히는 편이 안정적입니다.
• pagination.hasNext를 활용하세요. total로 페이지 수를 계산하는 것보다hasNext로 루프 종료를 판단하는 것이 구현이 단순하고 오차 발생 여지가 적습니다.
• Rate Limit을 고려하세요. 전체 목록을 빠르게 순회하면 일반 API 정책(300 req/분)을 초과할 수 있습니다. 상세는 Rate Limiting 문서를 참고하세요.