Pagination

The Propeller REST API implements pagination to efficiently handle large datasets and optimize performance. Pagination allows you to retrieve data in manageable chunks, reducing response times and resource usage.

Overview

When working with large collections of resources (products, orders, customers, etc.), pagination helps you:

• Improve Performance: Reduce response times and memory usage
• Control Resource Usage: Limit the amount of data transferred
• Enhance User Experience: Provide faster loading times for applications
• Optimize Network Usage: Reduce bandwidth consumption

How Pagination Works

Pagination in the Propeller API uses two main parameters:

• page: Specifies which page of results to retrieve
• offset: Controls how many results are returned per page

Page Parameter

The page parameter indicates which page of results you want to retrieve:

• Format: Integer (1, 2, 3, ...)
• Default: 1 (first page)
• Range: Must be a positive integer

Offset Parameter

The offset parameter controls the number of results returned per page:

• Format: Integer
• Default: 12 (most endpoints)
• Range: Minimum 1, maximum varies by endpoint
• Purpose: Limits the number of items returned in a single response

Pagination Parameters

GET Endpoints

For GET requests, pagination parameters are passed as query parameters:

# Get first page with 10 items per page
GET /v2/products?page=1&offset=10

# Get second page with 20 items per page
GET /v2/products?page=2&offset=20

# Get third page with default offset (12)
GET /v2/products?page=3

POST Search Endpoints

For POST search endpoints, pagination parameters are included in the request body:

{
  "filters": {
    "categories": ["electronics", "computers"]
  },
  "page": 1,
  "offset": 15
}

Pagination Response Format

All paginated responses include comprehensive pagination metadata:

{
  "data": [
    {
      "id": 56897,
      "name": "Product 1"
    },
    {
      "id": 36975,
      "name": "Product 2"
    }
  ],
  "messages": ["Completed"],
  "start": 1,
  "end": 2,
  "page": 1,
  "offset": 2,
  "total": 2,
  "pages": 20,
  "itemsFound": 35
}

Response Metadata

Field	Type	Description	Example
data	array	Array of resources for current page	[{...}, {...}]
start	integer	First item number on current page	1
end	integer	Last item number on current page	2
page	integer	Current page number	1
offset	integer	Number of items per page	2
total	integer	Number of items on current page	2
pages	integer	Total number of pages	20
itemsFound	integer	Total number of items across all pages	35

Pagination Best Practices

Effective Pagination Usage

** Choose Appropriate Page Sizes**

// For mobile applications - smaller pages
const mobileOffset = 10;

// For desktop applications - larger pages
const desktopOffset = 25;

// For data export - larger pages
const exportOffset = 100;

Common Pitfalls

** Requesting Too Many Items**

// Bad: Requesting too many items at once
const response = await fetch('/v2/products?page=1&offset=1000');

// Good: Use reasonable page sizes
const response = await fetch('/v2/products?page=1&offset=25');

Effective pagination is essential for building scalable applications with the Propeller REST API. Use appropriate page sizes and handle edge cases to optimize performance and user experience.