API Pagination

Learn how to work with paginated responses in the Mahalo Health API to efficiently retrieve large datasets.

Pagination Methods

The Mahalo Health API supports two pagination methods:

  1. Offset-based pagination: Using limit and offset parameters
  2. Cursor-based pagination: Using a cursor for more efficient pagination of large datasets

Offset-based Pagination

Offset-based pagination is suitable for smaller datasets and when you need to know the total count of items.

Request Parameters

ParameterTypeDefaultDescription
limitInteger20Number of items to return (max 100)
offsetInteger0Number of items to skip

Example Request

GET https://api.mahalo.health/v1/patients?limit=10&offset=20

Example Response

{
  "data": [
    {
      "id": "patient_21",
      "first_name": "Jane",
      "last_name": "Smith",
      // ... other patient fields
    },
    // ... 9 more patients
  ],
  "pagination": {
    "total_count": 145,
    "limit": 10,
    "offset": 20,
    "has_more": true
  }
}

Cursor-based Pagination

Cursor-based pagination is more efficient for large datasets and is recommended for most use cases.

Request Parameters

ParameterTypeDefaultDescription
limitInteger20Number of items to return (max 100)
cursorStringnullCursor pointing to the end of the previous page

Example Request

GET https://api.mahalo.health/v1/patients?limit=10&cursor=eyJpZCI6InBhdGllbnRfMjAifQ==

Example Response

{
  "data": [
    {
      "id": "patient_21",
      "first_name": "Jane",
      "last_name": "Smith",
      // ... other patient fields
    },
    // ... 9 more patients
  ],
  "pagination": {
    "limit": 10,
    "next_cursor": "eyJpZCI6InBhdGllbnRfMzAifQ==",
    "has_more": true
  }
}

Pagination Best Practices

  • Use cursor-based pagination for large datasets or when performance is critical
  • Use offset-based pagination when you need to know the total count or jump to a specific page
  • Always check the has_more field to determine if there are more items to fetch
  • Respect the maximum limit of 100 items per request
  • Implement proper error handling for pagination-related errors

Example: Fetching All Items

// JavaScript example of fetching all patients using cursor pagination
async function fetchAllPatients() {
  let allPatients = [];
  let cursor = null;
  let hasMore = true;
  
  while (hasMore) {
    const url = cursor 
      ? `https://api.mahalo.health/v1/patients?limit=100&cursor=${cursor}`
      : 'https://api.mahalo.health/v1/patients?limit=100';
      
    const response = await fetch(url, {
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
      }
    });
    
    const result = await response.json();
    
    allPatients = [...allPatients, ...result.data];
    cursor = result.pagination.next_cursor;
    hasMore = result.pagination.has_more;
  }
  
  return allPatients;
}