Pagination

Overview

Most list endpoints in our API return paginated results to maintain performance and manage data transfer efficiently. This document explains how our pagination works and how to navigate through paginated results.

Basic Usage

You can control pagination using the following query parameters:

• page: The page number to retrieve (starts at 1)
• limit: The maximum number of items per page

GET /v2/battery-assets/?page=1&limit=50

If not specified, the default values are:

• page: 1
• limit: 25

Response Format

Paginated responses have the following structure:

{
    "count": 120,           // Total number of items across all pages
    "next": "https://api.covolt.eu/v2/battery-assets/?page=2&limit=50",    // URL to next page (null if on last page)
    "previous": null,        // URL to previous page (null if on first page)
    "results": [            // Array of items for the current page
        {
            "uuid": "789cb490-2d71-40b1-bf58-45bb148dad5f",
            "asset_id": "123456789012345678",
            // ... other fields
        },
        // ... more items
    ]
}

Retrieving All Pages

Often, you'll need to retrieve all items across multiple pages. Here's how to approach this:

Sequential Page Retrieval

To retrieve all pages sequentially:

1. Make an initial request to the endpoint
2. Process the results array from the response
3. Check if the next field is not null
4. If next exists, make another request using the complete URL provided in the next field
5. Repeat steps 2-4 until next is null (indicating you've reached the last page)

This approach ensures you follow the API's intended pagination flow and handles any server-side pagination changes transparently.

Usage Tips

• Use the provided URLs: Always use the complete URLs from the next and previous fields instead of constructing your own URLs with page parameters.
• Respect rate limits: When fetching many pages, consider adding delays between requests to respect our API rate limits.
• Handle errors gracefully: Implement proper error handling if a page request fails.
• Consider pagination in UIs: If building a user interface, implement pagination controls that match our API's pagination model.