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.

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.

APIs to try it on

• Friends API — Characters, episodes & quotes from the coffee-house gang. (14 endpoints)
• Star Wars API — Characters, planets & starships from a galaxy far away. (11 endpoints)
• Bank API — Accounts, transfers & cursor pagination. Home of the 402. (9 endpoints)
• Search & Facets API — Full-text queries, facets, highlights & cursor pagination. (2 endpoints)

Status codes involved

• 200 OK
• 400 Bad Request
• 404 Not Found

Other techniques

• Rate limit testing — Trigger a real 429 with Retry-After and X-RateLimit headers, and verify your client backs off instead of retrying straight into the limit.
• Idempotency key testing — Send the same write twice with an Idempotency-Key and confirm the operation happens once — the mechanism that stops a network retry becoming a duplicate charge.
• ETag and If-Match testing — Provoke a 412 Precondition Failed by writing with a stale ETag — the check that stops two clients silently overwriting each other.
• Webhook signature testing — Register a callback, trigger a delivery, verify its HMAC signature, and confirm a tampered payload is rejected.
• OAuth and JWT testing — Run real client-credentials, authorization-code and device-code flows, then test what your client does when the token expires mid-session.
• Negative testing — Provoke 400, 401, 403, 404, 409, 418, 422, 429, 500 and 503 deliberately, and check your client handles each one differently.
• Async job testing — Start a long-running job, follow the 202 and its Location header, and poll to completion — including the failure and timeout paths.

Getting started guide · All 37 mock REST APIs