Pagination

List endpoints in the Batchmates API return paginated results to manage large datasets efficiently. By default, results are paginated with 15 items per page.

Pagination Parameters

Name
page
Type
integer
Description
Page number to retrieve (default: 1)
Name
per_page
Type
integer
Description
Number of items per page (default: 15, max: 100)

Response Structure

Paginated responses include metadata about the dataset:

{
  "success": true,
  "data": {
    "data": [
      { "id": 1, "title": "Campaign 1" },
      { "id": 2, "title": "Campaign 2" }
    ],
    "current_page": 1,
    "per_page": 15,
    "total": 150,
    "last_page": 10,
    "from": 1,
    "to": 15,
    "next_page_url": "https://batchmates-v2.revlv.com/api/v1//campaigns?page=2",
    "prev_page_url": null
  }
}

Metadata Fields

Name
data
Type
array
Description
Array of items for current page
Name
current_page
Type
integer
Description
Current page number
Name
per_page
Type
integer
Description
Items per page
Name
total
Type
integer
Description
Total number of items
Name
last_page
Type
integer
Description
Last available page number
Name
from
Type
integer
Description
Starting item index
Name
to
Type
integer
Description
Ending item index
Name
next_page_url
Type
string | null
Description
URL for next page (null if last page)
Name
prev_page_url
Type
string | null
Description
URL for previous page (null if first page)

Making Paginated Requests

Basic Pagination

Request the first page with default settings (15 items).

Request

GET

/v1/campaigns

curl https://batchmates-v2.revlv.com/api/v1//campaigns \
  -H "Authorization: Bearer {token}"

Custom Page Size

Specify custom page size (max 100).

Request

GET

/v1/campaigns

curl -G https://batchmates-v2.revlv.com/api/v1//campaigns \
  -H "Authorization: Bearer {token}" \
  -d per_page=50

Specific Page

Navigate to a specific page.

Request

GET

/v1/campaigns

curl -G https://batchmates-v2.revlv.com/api/v1//campaigns \
  -H "Authorization: Bearer {token}" \
  -d page=3 \
  -d per_page=20

Implementation Examples

JavaScript/TypeScript

async function fetchAllCampaigns() {
  let page = 1;
  let allCampaigns = [];
  
  while (true) {
    const response = await fetch(
      `https://batchmates-v2.revlv.com/api/v1//campaigns?page=${page}&per_page=50`,
      {
        headers: { 'Authorization': `Bearer ${token}` }
      }
    );
    
    const { data } = await response.json();
    allCampaigns.push(...data.data);
    
    if (page >= data.last_page) break;
    page++;
  }
  
  return allCampaigns;
}

PHP

function fetchAllDonations($token) {
    $page = 1;
    $allDonations = [];
    
    do {
        $response = Http::withToken($token)
            ->get('https://batchmates-v2.revlv.com/api/v1//donations', [
                'page' => $page,
                'per_page' => 50
            ]);
        
        $data = $response->json()['data'];
        $allDonations = array_merge($allDonations, $data['data']);
        
        $hasMore = $page < $data['last_page'];
        $page++;
    } while ($hasMore);
    
    return $allDonations;
}

React Hook

import { useState, useEffect } from 'react';

function usePaginatedCampaigns(perPage = 15) {
  const [campaigns, setCampaigns] = useState([]);
  const [page, setPage] = useState(1);
  const [total, setTotal] = useState(0);
  const [loading, setLoading] = useState(false);
  
  useEffect(() => {
    const fetchCampaigns = async () => {
      setLoading(true);
      const response = await fetch(
        `https://batchmates-v2.revlv.com/api/v1//campaigns?page=${page}&per_page=${perPage}`,
        { headers: { 'Authorization': `Bearer ${token}` } }
      );
      
      const { data } = await response.json();
      setCampaigns(data.data);
      setTotal(data.total);
      setLoading(false);
    };
    
    fetchCampaigns();
  }, [page, perPage]);
  
  return { campaigns, page, setPage, total, loading };
}

Best Practices

1. Use Reasonable Page Sizes

Balance between API calls and memory usage:

Small pages (15-25): Better for real-time updates
Large pages (50-100): Fewer requests, faster bulk operations

2. Cache Results

Cache paginated results to reduce API calls:

const cache = new Map();

async function getCampaigns(page) {
  const cacheKey = `campaigns-${page}`;
  
  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }
  
  const response = await fetch(/* ... */);
  const data = await response.json();
  
  cache.set(cacheKey, data);
  return data;
}

3. Handle Edge Cases

if (data.current_page > data.last_page) {
  // Redirect to last valid page
  window.location.href = `?page=${data.last_page}`;
}

if (data.total === 0) {
  // Show empty state
  return <EmptyState />;
}

4. Show Loading States

Always indicate when data is being fetched:

{loading ? (
  <Spinner />
) : (
  <CampaignList campaigns={campaigns} />
)}