Overview

Rackbeat APIs implement pagination to efficiently handle large datasets and improve performance when retrieving collections of resources. Instead of returning all records at once, the API breaks down results into manageable pages, allowing developers to request specific portions of data as needed.

How Pagination Works

When you make a request to list endpoints (such as /bank-accounts, /delivery-addresses, or /fields), the API returns paginated results with a 206 Partial Content status code, indicating that only a subset of the total data is being returned.

Response Structure

Paginated responses follow a consistent structure across all Rackbeat APIs:

Key Pagination Fields

total: The total number of records available across all pages
pages: The total number of pages available
limit: The maximum number of records returned per page (default: 20)
page: The current page number being returned

{
  "data_collection": [...],
  "total": 150,
  "pages": 8,
  "limit": 20,
  "page": 1
}

Navigating Through Pages

To retrieve different pages of results, you can use query parameters in your requests:

Use page parameter to specify which page to retrieve
Use limit parameter to control the number of records per page

For example:

GET /bank-accounts?page=2&limit=20

Best Practices

Always check pagination metadata: Use the total, pages, and page fields to understand the complete dataset size and your current position
Handle empty results: Be prepared for pages that may return empty collections
Implement proper error handling: Account for cases where you request a page number that exceeds the available pages
Consider performance: Requesting smaller page sizes can improve response times, especially for complex data

Search and Filtering

Pagination works seamlessly with search and filtering parameters. When you apply filters using the search parameter, the pagination metadata reflects the filtered results, not the entire dataset.

Understanding pagination is crucial for efficiently working with Rackbeat APIs, ensuring your applications can handle large datasets while maintaining optimal performance and user experience.