Getting Started

Pagination

The InChurch API uses cursor-based pagination for efficient navigation through large datasets. This guide explains how pagination works and provides best practices for implementing it in your applications.

Pagination Overview

All list endpoints in the InChurch API support pagination to:

• Improve Performance: Reduce response times and memory usage
• Reduce Bandwidth: Transfer only the data you need
• Prevent Timeouts: Avoid request timeouts on large datasets
• Enable Streaming: Process data in manageable chunks

Pagination Parameters

Request Parameters

Parameter	Type	Default	Max	Description
limit	integer	20	100	Number of items per page
offset	integer	0	-	Number of items to skip

Example Request

Code
 
GET /people?limit=50&offset=100

This request returns 50 people starting from the 101st person (skipping the first 100).

Response Format

Paginated Response Structure

All paginated responses include both data and metadata:

Code
 
{
  "count": 0,
  "next": "https://www.example.com/path/to/resource",
  "previous": "https://www.example.com/path/to/resource",
  "results": []
}

Metadata Fields

Field	Description
total	Total number of items across all pages
per_page	Number of items requested per page
current_page	Current page number (1-based)
last_page	Total number of pages
from	Index of first item on current page (1-based)
to	Index of last item on current page (1-based)

Best Practices

1. Use Appropriate Page Sizes

Use Case	Recommended Size	Reason
UI Lists	20-50	Good balance of performance and UX
Data Export	100	Minimize API calls
Real-time Processing	20-30	Quick response times
Background Jobs	50-100	Efficient batch processing
Mobile Apps	10-20	Reduce bandwidth usage

2. Handle Empty Results

Code
 
const response = await client.getPeople(page, limit);

if (response.data.length === 0) {
  if (response.meta.pagination.total === 0) {
    console.log('No people found');
  } else {
    console.log('No more pages');
  }
}

3. Implement Progress Indicators

Code
 
async function fetchAllWithProgress(endpoint, onProgress) {
  let page = 1;
  const limit = 50;
  let allData = [];
  
  const firstPage = await client.getPeople(page, limit);
  const totalPages = firstPage.meta.pagination.last_page;
  
  allData.push(...firstPage.data);
  onProgress({ current: 1, total: totalPages });
  
  for (page = 2; page <= totalPages; page++) {
    const response = await client.getPeople(page, limit);
    allData.push(...response.data);
    onProgress({ current: page, total: totalPages });
  }
  
  return allData;
}

4. Combine with Filtering

Code
 
// Paginate through filtered results
const activeMembers = await client.getPeople(1, 50, {
  status: 'active',
  is_leader: true
});

// Handle filtered pagination
if (activeMembers.meta.pagination.total === 0) {
  console.log('No active leaders found');
} else {
  console.log(`Found ${activeMembers.meta.pagination.total} active leaders`);
}