Pagination API Reference

This document details the pagination strategies employed by our API to manage large datasets efficiently. Proper pagination ensures that you can retrieve data in manageable chunks, reducing load times and improving the overall performance of your application.

Overview

Our API uses a cursor-based pagination system. This means that instead of using page numbers, you'll use cursors (unique identifiers) to fetch subsequent or previous sets of results. This approach is more robust for frequently updated datasets as it's not affected by items being added or removed between page requests.

Response Structure

Each paginated response will include the following fields:

• data: An array containing the retrieved items.
• links: An object containing URLs for navigating to the next and previous sets of results.
• meta: An object containing metadata about the current response, such as total counts or current page information.

Example Response

{
    "data": [
        { "id": 1, "name": "Item Alpha" },
        { "id": 2, "name": "Item Beta" },
        { "id": 3, "name": "Item Gamma" }
    ],
    "links": {
        "next": "/api/v1/items?cursor=next_cursor_id_abc123",
        "prev": "/api/v1/items?cursor=prev_cursor_id_xyz789"
    },
    "meta": {
        "totalItems": 150,
        "itemsPerPage": 10,
        "currentPage": 1
    }
}

Requesting Paginated Data

To request a specific page of results, you will append a cursor query parameter to the relevant endpoint. The value of this cursor is provided in the links.next or links.prev field of the previous response.

Fetching the First Page

To get the initial set of results, simply make a request to the endpoint without any cursor parameters.

GET /api/v1/items

Fetching Subsequent Pages

To fetch the next page, use the next URL provided in the links object of the previous response.

GET /api/v1/items?cursor=next_cursor_id_abc123

Fetching Previous Pages

To fetch the previous page, use the prev URL provided in the links object of the previous response.

GET /api/v1/items?cursor=prev_cursor_id_xyz789

Parameters

The primary parameter used for pagination is:

Metadata

The meta object in the response provides valuable context about the paginated data.