페이지네이션

목록 조회 API에서 사용하는 Offset 기반 페이지네이션 방식을 안내합니다.

개요

SweetBook API는 목록 조회 시 Offset 기반 페이지네이션을 사용합니다.limit과 offset 파라미터로 조회 범위를 지정하며, 응답에 포함된 hasNext 필드로 다음 페이지 존재 여부를 확인할 수 있습니다.

Query Parameters

파라미터	타입	기본값	설명
`limit`	`number`	`20`	한 번에 조회할 항목 수 (최대 200)
`offset`	`number`	`0`	건너뛸 항목 수

응답 구조

목록 조회 API의 data 필드에는 다음과 같은 페이지네이션 메타 정보가 포함됩니다.

json

{
  "success": true,
  "message": "Success",
  "data": {
    "total": 85,
    "limit": 20,
    "offset": 0,
    "hasNext": true,
    "items": [
      { ... },
      { ... }
    ]
  }
}

필드	타입	설명
`total`	`number`	전체 항목 수
`limit`	`number`	요청한 조회 수
`offset`	`number`	요청한 시작 위치
`hasNext`	`boolean`	다음 페이지 존재 여부
`items`	`array`	조회된 항목 목록

사용 예시

첫 번째 페이지 조회

bash

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

두 번째 페이지 조회

bash

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

전체 목록 순회 (JavaScript)

javascript

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

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

    allItems.push(...data.items);

    if (!data.hasNext) break;
    offset += limit;
  }

  return allItems;
}

Best Practices

적절한 limit 값을 사용하세요. 대부분의 경우 20~50이 적합합니다. 최대값(200)은 꼭 필요한 경우에만 사용하세요.
큰 offset 값은 피하세요. offset이 크면 데이터베이스 성능에 영향을 줄 수 있습니다. 수천 건 이상의 데이터를 순회해야 하는 경우, 날짜 필터 등을 활용하여 조회 범위를 좁히세요.
hasNext 필드를 활용하세요. total로 계산하는 것보다 hasNext로 다음 페이지 존재 여부를 판단하는 것이 더 안정적입니다.
Rate Limit을 고려하세요. 전체 목록을 순회할 때는 요청 간 적절한 간격을 두어 Rate Limit에 걸리지 않도록 하세요.