Testing pagination against a real API

Pagination looks trivial until a page boundary lands in the middle of a record set that is still being written to. The APIs below implement both common styles — page numbers with a total, and opaque cursors — so you can write a client against each and find out which assumptions your code is making.

Pagination testing — request and response sequence Sequence diagram for Pagination testing: GET /friends/v1/characters answers 200 OK. GET /friends/v1/episodes answers 400 Bad Request. GET /friends/v2/characters answers 404 Not Found. Your client Fun API Playground GET /friends/v1/characters 200 OK List all characters (paginated) — v1, deprecated GET /friends/v1/episodes 400 Bad Request List episodes, filter by season GET /friends/v2/characters 404 Not Found List characters — v2 (breaking change: job → occupation,…
Real endpoints from the catalog — every request above is served, and every status code shown is one that endpoint actually returns.

How to practise it

  1. Walk every page of a collection and assert that the number of records you collected equals the total the API reported.
  2. Request a page past the end of the collection. Some APIs answer with an empty list and a 200; the Friends API answers 404. Both are defensible, and your client has to handle whichever it meets.
  3. Check the last page: it is almost always partially full, and off-by-one errors hide there.
  4. Walk the Bank API by cursor and confirm no record is skipped or repeated — the failure mode cursors are supposed to prevent.
  5. Combine pagination with a filter and verify the counts still agree.

Test cursor pagination with Python

Install requests, then run this read-only example. It uses account 1 and an isolated sandbox; the demo token is public. Keep the same sandbox ID across all pages.

import uuid
import requests

url = 'https://funapi.dev/api/bank/v1/accounts/1/transactions'
headers = {
    'Authorization': 'Bearer qa-admin-token',
    'X-Sandbox-ID': str(uuid.uuid4()),
}
cursor = None
seen_ids = set()
seen_cursors = set()
while True:
    params = {'limit': 2}
    if cursor is not None:
        params['cursor'] = cursor
    response = requests.get(url, headers=headers, params=params, timeout=10)
    response.raise_for_status()
    page = response.json()
    for transaction in page['data']:
        assert transaction['id'] not in seen_ids, 'Repeated transaction'
        seen_ids.add(transaction['id'])
    cursor = page['nextCursor']
    assert page['hasMore'] == (cursor is not None)
    if cursor is None:
        break
    assert cursor not in seen_cursors, 'Repeated cursor'
    seen_cursors.add(cursor)
assert seen_ids, 'Expected seeded transactions'
print(f'Checked {len(seen_ids)} unique transactions')

The nextCursor value is opaque: pass it back unchanged. This test checks for duplicate records and cursor loops; a changing dataset requires additional consistency checks to prove no records were missed.

APIs to try it on

Status codes involved

Other techniques

Getting started guide · All 55 mock REST APIs

Last updated