Pagination, Part 1: The Model and Index-Based Paging

Every API that returns a list eventually returns it in pieces. The pieces are easy; walking them correctly is not. In this series we'll treat pagination formally: define what the server holds, define what each request returns as a function of its parameters, and then ask what a client can actually guarantee when it stitches the pieces back together.

Part 1 sets up the model and covers the two index-based methods, page and offset. Part 2 covers cursors: opaque tokens and key-based cursors, and the boundary problem that comes with keys that are not unique. Part 3 covers range walks over time or ids, where the crucial and rarely documented fact is which end the server truncates from. Part 4 is best practices for both sides, API designers and client authors, with a table of what real venues do.

The model

The server holds a finite sequence, totally ordered by some key $k$ : a timestamp, an id, a block height.

x_{1} < x_{2} < \dots < x_{n} ordered by k (x)

A paginated endpoint is a function of its parameters $θ$ that returns a contiguous slice of that sequence, at most $s$ rows long, plus some metadata:

f (θ) \to ([x_{a}, \dots, x_{b}], meta), b - a + 1 \leq s

The methods differ only in what $θ$ is and what $meta$ carries. That gives two independent questions a client has to answer for every endpoint:

Where is the next slice? Expressed as an index, an offset, an opaque token, or a key value.
When is the walk over? A published total, a page shorter than $s$ , an empty page, or an absent token.

Both answers are computed from the response to one request. Most pagination bugs are one of them being applied to the next request after the data has changed in between: the position has shifted, or the stop condition was decided on numbers that no longer hold.

Page-based

The client asks for page $i$ of size $s$ . Numbering pages from 0 keeps the arithmetic clean (most venues number from 1, which only shifts $i$ by one):

f (i, s) = [x_{i s + 1}, \dots, x_{m i n ((i + 1) s, n)}]

n = 12 rows, page size s = 4: the sequence is tiled into three slices, and page 1 (numbering from 0) is positions 5 to 8.

The server may also report a total, either as a count of items $n$ or as a count of pages $⌈ n / s ⌉$ . The two are not interchangeable: an item total needs $s$ to turn into a stop condition, and a caller who omits $s$ is using the server's default, which the client must know.

i ← 0
loop:
  rows, meta ← f(i, s)
  yield rows
  if rows is empty:                           stop   # always safe
  if meta.total is present:
    if counts pages and i + 1 ≥ meta.total:   stop
    if counts items and (i + 1)·s ≥ meta.total: stop
  else if |rows| < s:                         stop   # short page
  i ← i + 1

Two remarks. First, the empty-page test is the only one that is safe on its own: a short page is short relative to $s$ , so it needs $s$ to be known, and a total is a claim the server makes about $n$ at the moment of that request, which is a different moment from the previous page's. Second, a walk should never fail on a missing total. A page that omits it is a page you already have; carry on to the empty page.

Offset-based

Offset is page-based with the arithmetic done by the client:

f (o, s) = [x_{o + 1}, \dots, x_{m i n (o + s, n)}]

so page $i$ is offset $o = i s$ . The one real difference is how the walk advances. Advance by the rows you actually received, not by $s$ :

o ← 0
loop:
  rows, meta ← f(o, s)
  yield rows
  if rows is empty:  stop
  o ← o + |rows|
  (total and short-page tests as above)

Advancing by $s$ when the server returned fewer than $s$ rows, because its own cap is below your $s$ , skips rows silently. Advancing by $∣ rows ∣$ is correct in both cases.

Offset o = 6 asked for four rows and got three. The next offset has to be o + |rows| = 9, not o + s = 10, or x10 is never fetched.

When $n$ changes

So far $n$ was fixed, and both methods are trivially correct: the slices tile the sequence. Real history endpoints are not fixed; new fills, deposits and candles keep arriving during a walk. Consider the append-only case, $m$ new rows arriving after page $i$ was fetched.

If the server orders oldest first, the new rows land at positions $n + 1, \dots, n + m$ , past everything the walk has touched. Page $i + 1$ is exactly what it would have been. Append-only plus oldest-first is safe.

If the server orders newest first, which is what nearly every trade, order and transfer history endpoint does, every existing row shifts down by $m$ positions. Page $i + 1$ now starts at what used to be position $(i + 1) s + 1 - m$ :

f (i + 1, s) = [x_{(i + 1) s + 1 - m}, \dots, x_{(i + 2) s - m}]

Newest-first ordering: m = 2 rows arrive between the two requests, every position shifts by two, and page 1 re-serves the last two rows of page 0. The two new rows are never visited.

The last $m$ rows of page $i$ come back again at the top of page $i + 1$ . A deletion (a cancelled order disappearing from an open-orders list) does the opposite and skips $m$ rows. Under arbitrary insert, update and delete, neither method can promise anything. The guarantees a client can rely on:

	$n$ fixed	append, oldest first	append, newest first	arbitrary mutation
no duplicates	yes	yes	no	no
no gaps	yes	yes	yes	no

Two consequences follow. A page or offset walk over a live, newest-first endpoint has to deduplicate by a row identity (an id, or a key plus enough fields to be unique), because the walk itself cannot avoid re-serving rows. And a total that changes between two pages is not an anomaly worth aborting the walk over: it is the normal signature of the append case, and aborting on it buys no correctness, since the duplicates it implies are already in the rows the client holds. Use the total to stop, never to validate.

Closing