Skip to main content

REST pagination

Riseact's REST APIs use offset-based pagination via the limit and offset parameters. This is Django Ninja's standard behavior.

Parameters​

ParameterTypeDefaultDescription
limitint100Maximum number of items to return
offsetint0Number of items to skip from the beginning

Response structure​

Paginated lists return an object with the following fields:

{
  "items": [...],
  "count": 1250
}
  • items - array of items in the current page
  • count - total number of results (ignoring limit/offset), useful for computing the number of pages

Example​

First page (20 items):

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://core.riseact.org/api/v1/supporters/?limit=20&offset=0"

Second page:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://core.riseact.org/api/v1/supporters/?limit=20&offset=20"

Response:

{
  "items": [
    {
      "id": 1,
      "first_name": "Mario",
      "last_name": "Rossi",
      "email": "mario@example.com"
    }
  ],
  "count": 1250
}

Computing the number of pages​

const totalPages = Math.ceil(response.count / limit);

Fetching all items​

async function fetchAll(endpoint, token) {
  const limit = 100;
  let offset = 0;
  const results = [];

  while (true) {
    const res = await fetch(
      `https://core.riseact.org/api/v1/${endpoint}/?limit=${limit}&offset=${offset}`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    const { items, count } = await res.json();

    results.push(...items);
    offset += limit;

    if (offset >= count) break;
  }

  return results;
}

Ordering​

Every REST endpoint accepts an order parameter to specify the ordering field. The - prefix indicates descending order.

# Donations ordered by date ascending
GET /api/v1/donations/?order=create_date

# Donations ordered by date descending (default)
GET /api/v1/donations/?order=-create_date

The default for all endpoints is -create_date (most recent first).

Endpoints that support pagination​

EndpointMethod
/api/v1/supporters/GET
/api/v1/donations/GET
/api/v1/payments/GET
/api/v1/campaigns/GET
/api/v1/checkouts/GET