Pagination

Paginated Response Format

Responses from paginated endpoints are structured as follows:

{
    "data": {
        "items": [],              // The actual data items for the current page
        "total_items": 0,         // The total number of items across all pages
        "page": 1,               // The current page number
        "limit": 10,             // The number of items per page (page size)
        "total_pages": 1          // The total number of pages available
    }
}

Fields:

• items: An array containing the actual data items for the current page.
• total_items: The total number of items across all pages.
• page: The current page number.
• limit: The number of items per page, also referred to as the page size.
• total_pages: The total number of pages available given the current page size.

Requesting Specific Pages and Page Sizes

To request a specific page or change the page size (limit), use the page and limit query parameters, respectively.

• page (optional): Specifies which page number you want to retrieve. If not provided, defaults to the first page.
• limit (optional): Defines how many items you want to retrieve per page. If not provided, a default size (e.g., 10 items) is used.

Best Practices for Pagination

1. Navigating through Pages: Begin with page=1 and incrementally adjust the page number until the returned total_pages value is met.
2. Tailoring Page Size: If dealing with numerous minor entries or if bandwidth isn't a concern, consider amplifying the limit. In contrast, reduce the limit if data items are extensive or bandwidth is constrained.
3. Managing Extensive Datasets: Constantly monitor total_items and total_pages. With significantly large datasets in view, employ strategies like filtering or sorting to minimize the items you need to process.