# 페이지네이션

> 모든 Kanorio API의 목록 엔드포인트는 limit와 cursor를 사용하여 데이터를 가져오며 hasMore와 nextCursor를 반환합니다.

> Markdown version of https://kanorio.com/ko/developers/basics/pagination. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/basics/pagination.md

Management API, Content Delivery API, Customer API의 모든 목록 엔드포인트는 동일한 방식으로 페이지네이션을 처리합니다.

## 요청

| 매개변수 | 유형 | 기본값 | 참고 사항 |
|---|---|---|---|
| `limit` | 정수 | 20 | 1부터 100까지입니다. 일부 엔드포인트는 더 낮은 최댓값을 명시합니다. |
| `cursor` | 문자열 | 없음 | 이전 페이지의 `nextCursor`입니다. 첫 페이지에서는 생략하십시오. |

## 응답

```json
{
  "data": [{ "id": "post_example01" }, { "id": "post_example02" }],
  "hasMore": true,
  "nextCursor": "eyJvIjoyMCwicyI6ImFiYzEyMyJ9"
}
```

| 필드 | 유형 | 참고 사항 |
|---|---|---|
| `data` | 배열 | 엔드포인트 순서에 따른 해당 페이지의 항목입니다. |
| `hasMore` | 불리언 | 다음 페이지가 존재할 경우 `true`입니다. |
| `nextCursor` | 문자열 또는 null | 다음 페이지를 가져오려면 `cursor`로 전달하십시오. 마지막 페이지에서는 `null`입니다. |

일부 엔드포인트는 여기에 추가 필드를 포함합니다. 예를 들어, 컬렉션 아이템 엔드포인트는 페이지에서 참조하는 모든 이미지와 파일을 맵 형태로 담은 `assets` 필드를 추가합니다.

## 규칙

- **커서는 불투명한 값입니다.** 커서를 파싱하거나, 직접 생성하거나, 장기간 저장하지 마십시오. 커서 형식은 예고 없이 변경될 수 있습니다.
- **다른 매개변수를 유지하십시오.** 커서는 해당 커서가 발행될 때 사용된 필터, 정렬, 제한 설정에 종속됩니다. 다른 필터와 함께 커서를 보내면 `400 INVALID_CURSOR` 오류가 발생합니다. 필터를 변경할 때는 커서 없이 처음부터 다시 시작하십시오.
- **페이지 번호나 오프셋을 사용하지 않습니다.** API는 `page`, `pageSize`, `offset` 매개변수를 허용하지 않습니다.
- **기본적으로 전체 개수를 반환하지 않습니다.** 모든 일치 항목을 계산하는 것은 비용이 많이 들기 때문에 목록은 전체 개수를 반환하지 않습니다. Content Delivery API에서는 컬렉션 아이템과 검색 두 엔드포인트가 `total=true`를 전달하면 `total` 값을 반환합니다(검색의 전체 개수는 결과와 같은 쿼리에서 계산됩니다).
- **짧은 목록도 엔벨로프를 사용합니다.** Webhook 엔드포인트나 리다이렉트와 같이 고정된 작은 제한이 있는 목록도 `hasMore: false`와 함께 한 페이지에 모든 결과를 반환합니다. 자세한 내용은 각 참조 페이지를 확인하십시오.

## 모든 페이지 읽기

```bash
curl "https://app.kanorio.com/api/v1/sites/ws_example123/posts?limit=50" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

# then, while hasMore is true
curl "https://app.kanorio.com/api/v1/sites/ws_example123/posts?limit=50&cursor=eyJvIjo1MH0" \
  -H "Authorization: Bearer $KANORIO_TOKEN"
```

SDK의 `paginate`는 `nextCursor`를 자동으로 추적하며 모든 목록 엔드포인트에서 작동합니다.

```ts
import { createManagementClient, paginate } from "@kanorio/sdk";

const client = createManagementClient({ token: process.env.KANORIO_TOKEN! });

for await (const post of paginate((cursor) =>
  client.get("/sites/{id}/posts", { params: { id: "ws_example123" }, query: { limit: 50, cursor } })
)) {
  console.log(post.slug);
}
```

전체 목록을 배열로 가져오려면 `paginate` 대신 `listAll`을 사용하십시오.