Pagination Guide

Navigate large assessment datasets reliably using ALOC’s cursor-based pagination standard.

1.2.0Overview

ALOC uses Cursor-Based Pagination rather than traditional offset or page-number pagination (e.g. ?page=2).

Zero Data Drift

As new questions or metadata are continuously published, cursor-based pointers ensure you never see duplicated or skipped items during pagination.

Predictable Performance

Queries execute in O(1) indexed lookup time regardless of how deep you paginate into the dataset, avoiding expensive database OFFSET scans.

1.2.1How it works

Initial Query (Page 1) — Make a standard GET request with your filter criteria (e.g. subject=mathematics) without passing a cursor.
Inspect the Response — Every paginated response includes a pagination object with nextCursor and hasMore.
Fetch Next Page — Take the string from pagination.nextCursor and pass it as the ?cursor= parameter in your next request.
Detect Completion — When hasMore is false (and nextCursor is null), you have reached the end of the dataset.

1.2.2Request & Response Structure

Below is an example of an initial response showing the pagination block:

{
  "data": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "subject": "mathematics",
      "text": "Solve for x: 3x + 12 = 27",
      "options": { "a": "3", "b": "5", "c": "7", "d": "9" },
      "correctAnswer": "b"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6IjliMWRlYjRkLTNiN2QtNGJhZC05YmRkLTJiMGQ3YjNkY2I2ZCJ9",
    "prevCursor": null,
    "hasMore": true
  },
  "meta": {
    "creditsUsed": 1,
    "creditsRemaining": 999
  }
}

To fetch page 2, supply that nextCursor:

GET/v1/questions?subject=mathematics&cursor=eyJpZCI6IjliMWRlYjRkLTNiN2QtNGJhZC05YmRkLTJiMGQ3YjNkY2I2ZCJ9

1.2.3Code Examples

Copy and paste full pagination loops in your language of choice:

// Node.js & Browser: Automatic cursor-based pagination loop
async function fetchAllQuestions(subject) {
  let cursor = null;
  let hasMore = true;
  const allQuestions = [];

  while (hasMore) {
    const url = new URL("https://dev.aloc.com.ng/api/v1/questions");
    url.searchParams.set("subject", subject);
    url.searchParams.set("limit", "10");
    if (cursor) {
      url.searchParams.set("cursor", cursor);
    }

    const res = await fetch(url.toString(), {
      headers: {
        "X-API-Key": "alc_live_7f3a91c2d8e4f1ab92dd",
        "Accept": "application/json",
      },
    });

    const body = await res.json();
    const questions = body.data || [];
    allQuestions.push(...questions);

    // Update cursor and termination flag
    cursor = body.pagination?.nextCursor ?? null;
    hasMore = Boolean(body.pagination?.hasMore);
  }

  return allQuestions;
}

1.2.4Parameters & Schema Reference

Query Parameters

PARAMETERTYPEDESCRIPTION

cursorstringOpaque pointer returned from previous request.

limitintegerNumber of results per page (default: 10, maximum: 15).

Pagination Schema Object

FIELDTYPEDESCRIPTION

nextCursorstring | nullThe cursor pointer for the next page. null when no further results exist.

prevCursorstring | nullThe cursor pointer for the previous page.

hasMorebooleanBoolean flag indicating whether more pages exist beyond this one.

1.2.5Best Practices & Optimization

Follow these recommended patterns to build resilient and high-throughput pagination workflows:

Apply Specific Filter Criteria

Instead of paginating through the entire question bank, narrow your queries using subject, examType, or year. Filtered indexes return results significantly faster.

Configure Page Limits (1–15)

The default page size is 10 items with a maximum limit of 15 per request. To maximize throughput per request, pass limit=15.

Respect Rate Limits in Automated Loops

When running background workers that traverse multiple pages, inspect the X-RateLimit-Remaining header and implement exponential backoff if a 429 Rate Limited response is returned.