Pagination

Some endpoints may return a large number of results, so pagination is available to help you request only a subset of the results at a time.

Types of pagination

There are two types of pagination used underneath:

• Page-based pagination: This method uses a paging parameter to indicate the starting point of records to return.
• Cursor-based pagination: This method utilizes a unique identifier to determine the position in the data set.

There are different advantages and disadvantages to each method, but performance wise cursor-based pagination is generally more efficient.

Currently, most of the endpoints are offset-based, but they are being migrated to cursor-based. To make this transparent to you, the pagination response object is standardized to work with both methods.

Pagination in responses

When an endpoint supports pagination, the response will include a pagination object with the following properties:

• next: The URL to the next page. This property will be omitted if the result set is empty or if the next page has no results.
• previous: The URL to the previous page. This property will be omitted if the result set is empty or if there’s no previous page.
• first: The URL to the first page. This property will be omitted if the result set is empty.

Here are a few examples of how the pagination object may look like in the response:

On first page

{
  "pagination": {
    "first": "https://api.enterprise.uphold.com/core/transactions?page=1&perPage=10",
    "next": "https://api.enterprise.uphold.com/core/transactions?page=2&perPage=10",
  }
}

Make sure to use these URLs when requesting pages instead of hardcoding them, otherwise your implementation may break as endpoints migrate to cursor-based pagination in the future.

Number of results per page

To control how many results are returned per page, you can use the perPage query parameter. For example, to request 100 results per page, you would add perPage=100 query parameter to the URL.

The perPage parameter will automatically be included in the URLs in the pagination object, so you don’t need to worry about it when following the pagination links.