HTTP API Pagination Testing Guide: Verify Cursors, Limits, Sorting, and Duplicate-Free Results
apipaginationintegration-testingrestbackend-development

HTTP API Pagination Testing Guide: Verify Cursors, Limits, Sorting, and Duplicate-Free Results

CClicky Editorial Team
2026-11-16
8 min read

A practical checklist for testing API pagination, including cursors, limits, sorting, data changes, edge cases, and duplicate-free traversal.

Reliable pagination testing proves that an API returns every expected record exactly once under realistic changes, limits, sorting rules, and failure conditions. This guide gives you a reusable checklist for testing page-number, offset, cursor, and keyset pagination, with fixtures, comparison points, troubleshooting steps, and maintenance reminders.

Overview

Pagination divides a large collection into smaller responses so clients can retrieve data without requesting the entire dataset at once. The implementation may look simple, but defects often appear at boundaries: the first or last page, a requested limit above the allowed maximum, a changing dataset, or a sort order that is not deterministic.

A useful pagination test does more than confirm a 200 OK response. It checks the contract and the result set together:

  • The response uses the documented pagination parameters and metadata.
  • The requested page size is honored or safely constrained.
  • Records are not duplicated or skipped when pages are combined.
  • Sorting is stable and consistent across requests.
  • Empty, malformed, expired, and over-deep requests have defined behavior.
  • Changes to the underlying data do not create unexplained gaps or repeats.

Before testing, record the endpoint, authentication requirements, default and maximum page sizes, supported sort fields, filter behavior, and pagination fields such as next, previous, offset, limit, or cursor. An HTTP request testing workflow can help you capture repeatable requests and responses, while an OpenAPI validation workflow can help compare implementation behavior with the published contract.

Pagination models at a glance

ModelHow it worksGood fitMain test concern
Page numberRequests use a page number and often a page size.User-facing lists and simple administration screens.Boundary pages, invalid page numbers, and changes between requests.
Offset and limitRequests start after a numeric offset and return a limit.Small or moderately changing collections and straightforward queries.Inserted or deleted rows can shift later offsets and cause skips or duplicates.
CursorA token identifies where the next request should continue.Large, changing, or continuously consumed collections.Token integrity, expiry, scope, sort consistency, and replay behavior.
KeysetThe next request uses values from the last item, such as an ID and timestamp.Efficient ordered retrieval over large datasets.Unique tie-breakers, null handling, and records changing sort position.

Checklist by scenario

1. Establish a deterministic fixture

Seed a known collection with enough records to cross several page boundaries. Include records with adjacent and repeated-looking sort values, long and short identifiers, null or optional fields where permitted, and records that differ only in the final tie-breaker. Assign each fixture a stable ID so the test can compare sets rather than relying only on response order.

A practical request-and-response fixture can follow this shape:

Request: GET /items?limit=3&sort=created_at,id&direction=asc
Expected status: 200
Expected item IDs: [item-001, item-002, item-003]
Expected next link or cursor: present
Expected count field: documented meaning and value

Keep the expected behavior explicit. A field named count might mean the current page size, the total matching records, or a count that is omitted for performance reasons. Test what the API documents rather than assuming a universal meaning.

2. Test normal page traversal

Request the first page with the default size, follow the supplied continuation value, and continue until the API indicates that no page remains. Record every ID in traversal order. Then verify that the combined result has the expected number of unique records and matches the fixture set.

  • Check the first page, one middle page, and the final page separately.
  • Compare the requested limit with the number of returned items.
  • Confirm that a non-final full page includes a usable continuation value.
  • Confirm that the final page does not point to another valid page.
  • Repeat the same request to check whether ordering is stable.

3. Test limits and page sizes

Try the documented default, the smallest valid value, a typical value, the maximum allowed value, zero, a negative value, a decimal, a very large value, and a non-numeric value. The API should either reject invalid input consistently or normalize it according to its contract. Do not treat silent normalization as correct unless it is documented.

Also test whether a client can request a page size larger than the server maximum. A safe response may cap the result, return a validation error, or use another documented rule. Whichever behavior is selected, verify that response metadata and continuation links reflect the actual behavior.

4. Test sorting and filtering together

Pagination is only reproducible when the ordering is stable. Test each supported sort field in both directions where applicable, then add filters and repeat the traversal. If several records share the primary sort value, the API needs a deterministic tie-breaker, commonly a unique ID. Without one, records can move between requests even when the dataset does not change.

Change one filter at a time, then combine filters. Verify that continuation links or cursors preserve the filter and sort settings. A cursor that is valid for one query should not silently be reused for a different filter or order.

5. Test inserts and deletes during traversal

For offset or page-number pagination, request an early page, insert a record that sorts before a later page, and then continue. Repeat with a deletion. Look for skipped or duplicated IDs. These outcomes may be an inherent trade-off of the model rather than a defect, but they should be understood and documented.

For cursor and keyset pagination, perform the same experiment. Confirm the intended consistency behavior: for example, whether the traversal represents a moving view, a stable snapshot, or a best-effort sequence. Do not infer snapshot guarantees from the presence of a cursor alone.

6. Test empty and exhausted collections

Run the endpoint with no matching records and with a valid request beyond the final page. Check whether the API returns an empty array, pagination metadata, links, and a consistent status code. Test an empty intermediate page if the API can produce one through filtering or concurrent changes. The client should not assume that an empty page always means the entire traversal is complete unless the contract says so.

7. Test cursor and keyset failures

For cursor-based APIs, submit a missing, malformed, truncated, modified, expired, or cursor from another endpoint or query. Verify that the server returns a controlled client error rather than an unrelated server failure. Check whether cursors are opaque to clients; clients should normally store and replay them rather than parse or construct them.

For keyset pagination, test records with equal timestamps, null sort values, changing sort values, and boundary values at the start and end of the collection. Confirm that the comparison operators produce neither an overlap nor a gap at the boundary.

8. Test maximum depth and resource protection

Traverse enough pages to reach any documented maximum depth, retention boundary, or rate limit. Check the response when the limit is reached and ensure that the client can distinguish an intentional restriction from an empty result. If pagination is exposed to public or untrusted clients, verify that very large limits, repeated cursor use, and deep offset requests receive predictable handling.

What to double-check

Use this review list before marking an endpoint complete:

  • Ordering: Is the order explicit, stable, and backed by a unique tie-breaker?
  • Continuation: Does the next link or cursor preserve filters, sorting, tenant scope, and page-size rules?
  • Boundary arithmetic: Do the first item of one page and the last item of the previous page meet exactly once?
  • Data mutations: Are inserts, updates, and deletes handled according to an intentional consistency model?
  • Validation: Are zero, negative, oversized, malformed, and missing parameters tested?
  • Security: Does a cursor or offset prevent access outside the caller's authorized scope?
  • Performance: Do deep offsets, large limits, and expensive sorts behave within the endpoint's intended budget?
  • Contract: Do examples, schema definitions, status codes, and actual responses agree?

When investigating a suspicious response, preserve the exact URL, headers relevant to scope or caching, request time, response body, and database fixture state. If query encoding is involved, use the URL query string guide to distinguish a pagination defect from incorrectly encoded parameters. For response bodies containing nested data, a JSON formatter or the API payload debugging workflow can make comparison easier.

Common mistakes

Testing only the happy path

A single request with the default limit does not test pagination. It misses invalid input, the final page, duplicate sort values, changing records, and continuation failures. Add boundary and mutation cases to the integration suite.

Comparing counts instead of identities

Two pages can contain the same number of items while one record is repeated and another is missing. Collect stable identifiers and compare both the total count and the unique-ID set.

Using an unstable sort

Sorting only by a non-unique timestamp, status, or name can make page boundaries nondeterministic. Add a unique secondary key and verify its direction and null behavior.

Assuming cursor pagination means snapshot consistency

A cursor may encode a position, query state, or expiration information, but its exact guarantees depend on the implementation. Test and document what happens when the source collection changes.

Ignoring client behavior

Test the consumer as well as the server. Confirm that it follows the continuation value, stops correctly, avoids infinite loops, handles repeated cursors, and does not silently discard records. Keep retry behavior separate from pagination logic so a transient retry does not create accidental duplication in downstream processing.

When to revisit

Re-run this checklist whenever a list endpoint is added, its database query changes, a sort field or filter is introduced, or the pagination model moves from offset to cursor or keyset. Repeat it after database migrations, index changes, ORM upgrades, API contract revisions, and changes to authentication or tenant scoping. A change that appears unrelated to pagination can still alter ordering, null handling, query plans, or authorization filters.

Before a planned release or seasonal traffic cycle, refresh the fixture and confirm the documented default and maximum limits, continuation format, error responses, and SDK behavior. If the endpoint is consumed by several clients, test representative clients after changing response metadata or link construction. Review provider and framework documentation when commonly used libraries or API standards change rather than copying old examples forward.

For an actionable final pass, create one automated test that traverses a stable fixture, one that changes data between pages, one that exercises invalid limits, and one that corrupts a continuation value. Store the captured requests and expected ID sets with the endpoint tests. This gives future maintainers a clear way to detect skipped records, duplicate records, unstable ordering, and contract drift before those issues reach users.

Related Topics

#api#pagination#integration-testing#rest#backend-development
C

Clicky Editorial Team

Developer Tools Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.