Introduction

This document provides guidance on implementing pagination in a REST API. Pagination helps manage large datasets by breaking them into smaller, more manageable chunks.

We've built in a default limit on results, but we recommend you always explicitly set the limit parameter to ensure you know how many results per page you'll get. Don't rely on the defaults as they'll be different depending on what parts of the response you're expanding, so the response you get might not be what you expected.

Pagination Parameters

The API uses two query parameters for pagination:

• page (integer, default: 1): Specifies the page number to retrieve.
• limit (integer, default: 5): Defines the number of records per page.

Request Format

GET /api/resources?page=1&limit=5

Response Fields

• page: The current page number.
• limit: The number of items per page.
• totalPages: The total number of pages available.
• totalDocs: The total number of items available in the dataset.
• docs: An array of items for the current page.
• hasPrevPage: Indicates whether there is a previous page of results available; true means you can navigate back, while false means you are on the first page
• hasNextPage: Indicates whether there is a next page of results available; true means more results can be fetched, while false means you have reached the last page.
• prevPage: Contains the URL for the previous page of results if available; null indicates there is no previous page.
• nextPage: Contains the URL for the next page of results if available; null indicates there is no next page.

How do I know if there are more pages?

When working with paginated results from the REST API, you can easily determine if more pages are available by checking the hasNextPage indicator in the response.

Checking for More Pages

• If hasNextPage is true, it indicates that there is another page of results available.
• Conversely, if hasNextPage is false, it means you have reached the last page of results, and there are no further items to retrieve.

Example Response

Here’s an example response where hasNextPage is true:

{
    "success": true,
    "response": {
              "docs": [
                {
                 // Data as per the resource    
                }
            ],
            "totalDocs": 4,
            "totalPages": 4,
            "page": 1,
            "limit": 1,
            "pagingCounter": 1,
            "hasPrevPage": false,
            "hasNextPage": true,
            "prevPage": null,
            "nextPage": 2       
    }
}

GET the next page of results

You can then make a call to return the next page. Increase the count of page by 1, so the next page of results will show items 5 through 9.

The call will be as follows:

GET /api/resources?page=2&limit=5