Proposal for Pagination Documentation

Summary

Pagination in an API helps in managing large sets of data by dividing it into smaller, more manageable chunks (see Paginated Lists in API Responses). This document provides an overview of how pagination works, the properties of paginated responses, and how to navigate through the paginated data.

How Pagination Works

When consuming an API that supports pagination, the data is returned in chunks or pages. Each paginated response typically includes metadata that helps in navigating through the pages.

Basic Usage

When you make a request to an API endpoint that supports pagination, you will receive a response with a limited set of data along with pagination metadata.

Example

Suppose you are requesting a list of groups from the API:

GET /api/group?page=1

The response might look like this:

{
    "@context": "https://grcschema.org/",
    "@id": "https://api.app.unifiedcompliance.com/api/group",
    "@type": "PaginatedList",
    "itemType": "Group",
    "page": 1,
    "perPage": 10,
    "total": 12,
    "previousPage": null,
    "nextPage": "https://api.app.unifiedcompliance.com/api/group?page=2",
    "items": [
        {
            "@type": "Group1",
            "@id": "https://api.app.unifiedcompliance.com/api/group/1",
            "elementId": 1,
            "description": "This is the first group"
        },
        {
            "@type": "Group2",
            "@id": "https://api.app.unifiedcompliance.com/api/group/2",
            "elementId": 2,
            "description": "This is the second group"
        },
        {
            "@type": "Group3",
            "@id": "https://api.app.unifiedcompliance.com/api/group/3",
            "elementId": 3,
            "description": "This is the third group"
        },
        ...
    ]
}

Paginated Response Properties

A paginated response usually contains the following properties:

• items: An array of items for the current page.
• page: The current page number.
• perPage: The number of items per page. The default value is 10 while the maximum value of this is typically 100
• total: The total number of items.
• previousPage: The URL for the previous page. This will be null when there is no previous page such as the first page
• nextPage: The URL for the next page. This will be null when there is no next page such as the last page

Example

Using the response from the example above, here’s how you can navigate through the pages:

• To get the next page of users, use the URL from the nextPage link:

GET /api/group?page=2

• To go back to the previous page, use the URL from the previousPage link:

GET /api/group?page=1

• To increase the items per page to 25, add the perPage parameter to the url

GET /api/group?page=1&perPage=25