Resource Representations

Pagination

A paginated result set is returned when multiple representations may exist in the result set that exceed a preset size. This breaks the result set into chunks (pages), each with its own page number. The page size is determined by the requesting user’s configuration of the field “Rows per Page”. This is the same field used to set the number of results per UI page returned. It has an allowed range of 10 to 125 results per page.

Pagination Mode

Two modes of pagination are supported that offer different advantages and disadvantages depending on the user requirements. The default mode is “paged”, but users may specify the type of pagination by using the “page_mode” query string parameter in the URI. The two types are “paged” and “sequenced”.

Mode: Paged

This is the default mode for result sets (…/resource/?page_mode=paged). This will break the data into chunks (pages) and return one page per request. This will additionally return metadata such as the total count of results and the total number of pages.

Each page of the result set is given a pagination header:

result_count – The total number of results across all pages.
page_count – The total number of pages.
page_nbr – The current page number.
next_page – Hyperlink to the next page (if available).
previous_page – Hyperlink to the previous page (if available).
results – The result set list for the page.

A specific page number for a paginated result set is requested in the URI’s query string using the parameter “page”. For example, to request the data for page 3 of a result set, one would add …/resource/?page=3. You will also see these automatically added in the hyperlinks generated for “next_page” and “previous_page”.

An example of a paginated JSON response:

{

"result_count": 1,

"page_count": 1,

"page_nbr": 1, "next_page": null, "previous_page": null, "results":
      [

{

"id": 0,

…

},

]

}

An example of a paginated XML response:

<?xml version="1.0" encoding="utf-8"?>

<entity_name>

<result_count>1</result_count>

<page_count>1</page_count>

<page_nbr>1</page_nbr>

<next_page></next_page>

<previous_page></previous_page>

<results>

<list-item>

<id>0</id>

…

</list-item>

</results>

</entity_name>

Mode: Sequenced

The sequenced mode (…/resource/?page_mode=sequenced) is similar to the Paged mode, except for a few important details. This mode is recommended for system to system integration where superfluous information and intuitive/human-readable values are not necessary.

Each page of the result set is given a header that conveys extra information to the user and makes it easier to navigate between pages:

next_page – Hyperlink to the next page (if available).
previous_page – Hyperlink to the previous page (if available).
results – The result set list for the page.

First, you’ll notice that the pagination header does not have the total result count or total page count. This is because sequenced pagination doesn’t know either of these values, and doesn’t want to. Instead, each page is generated on the fly in an effort to improve performance, which means less work than paged mode where the total counts are fetched up front. Determining total count can be expensive when you have a large result set.

With sequenced, you also sacrifice some human readability and functionality as the “page” query string parameter is replaced by a system-generated “cursor” as well as the hyperlinks will not be as intuitive to understand. Since in this mode the total result set is not known, only what’s rendered per page, there is no way to report the total number of pages or label each with a specific page number. A cursor identifier is generated for each page instead of a page number:

…/resource/?cursor=cD0xNDAw&page_mode=sequenced

Non-Paginated Responses

There are a few scenarios where a request will return data in the body of the response for a specific object, so pagination is not needed.

The first is for a GET retrieve style request where the “id” value of the resource is known and is requested in the URI (…/resource/{id}/).

The second is when creating a single resource using a POST request. The response will be a non-paginated representation for only the new resource.