페이지 매김

페이지 매김(pagination)은 목록 조회 API를 호출할 때 응답 결과를 여러 페이지로 구성하는 방법을 가리킨다. 목록을 조회하는 GET 메서드에서 주로 사용되며, 응답 본문의 페이로드가 큰 경우에 유용하다.

커서 기반의 페이지 매김 {#cursor-type-pagination}

NAVER WORKS API에서는 커서(cursor) 기반의 페이지 매김을 제공한다. 커서는 조회된 데이터의 마지막 부분을 가리키는 포인터로서, 페이지 매김을 제공하는 목록 조회 API를 호출하면 응답 본문에 추가되어 제공된다.

참고

일부 목록 조회 API는 페이지 매김 기능을 제공하지 않는다.

기존의 오프셋 기반 페이지 매김 방식은 조회 과정에서 일어날 수 있는 데이터의 추가나 삭제에 유연하게 대응하지 못하고 데이터가 중복, 유실되어 조회되거나 조회 결과를 별도로 재가공해야 하는 단점이 있었다.

커서 기반의 페이지 매김은 목록 전체를 검색하지 않고 조회된 마지막 부분을 기준으로 일정량의 데이터만 가져오는 방식으로 기존 방식의 단점을 보완했다. 따라서 이전 조회 목록과 중복되지 않는 데이터 검색을 보장하며 훨씬 빠르고 효율적으로 데이터를 가져올 수 있다.

사용 방법 {#how-to-use-pagination}

목록 조회 API 호출 결과의 응답 본문에서 아래와 같이 responseMetaData.nextCursor 항목에 커서가 포함되어 있다.

HTTP/1.1 200 OK{    "calendars": [        {            .....        },        {            .....        }    ],    "responseMetaData": {        "nextCursor": "kBhFZjtIFJKDiX1rE78vAg=="    }}

목록을 계속해서 조회할 경우에는 이 값을 QueryParam의 cursor 파라미터에 입력하여 API를 호출한다. 페이지의 마지막에 도달하여 더 이상 새로운 페이지가 없으면 responseMetaData.nextCursor가 반환되지 않는다.

목록 조회 단위 {#request-record-count}

한 번에 읽어올 객체의 개수를 지정할 수 있으면 count 파라미터를 제공한다. count 파라미터 없이 호출하면 각 API에서 미리 정의된 값으로 지정된다. count값은 maxCount값을 초과할 수 없다.