Visual walkthrough — REST API design — resources, HTTP methods, status codes, versioning, pagination

We will only assume you know what a list of items is (like rows in a spreadsheet). Everything else — index, window, offset, ceiling — we define as it appears.

---

Step 1 — What is the raw thing we are cutting up?

WHAT. Imagine your database table is just a tall stack of items in a fixed order. We draw them as boxes stacked top to bottom.

WHY. Before we can talk about "page 3" we must agree on what a page is made of. It's made of items sitting at positions. So first, positions.

PICTURE. In the figure, each box is one item (a user). To its left is a number called the index — the item's position counted from zero. The first item is at index $0$, the next at index $1$, and so on. We count from $0$ (not $1$) because almost every programming language and database slices lists that way; matching it avoids off-by-one bugs.

---

Step 2 — What is a "page"? A window of fixed height

WHAT. A page is a contiguous block of items — a window — of a fixed height we call $L$ (the page size / "limit"). Here we pick $L=3$ so it fits on screen.

WHY. We paginate because sending 50 million items at once is slow and wasteful; the client only wants one screenful. So we hand back one window at a time. The window has a chosen height $L$ so the client (and our server memory) always knows the maximum work per request.

PICTURE. The coloured bracket in the figure is one window of height $L=3$. Slide that same-height bracket down the stack and each position gives you a different page.

---

Step 3 — Where does page $p$ start? Discovering the offset

WHAT. Label pages the way humans do: page $1$, page $2$, page $3$ (1-indexed — humans start counting at one, even though item indices start at zero). We want: for page number $p$, which item index does the window's top sit on? Call that number the offset — the count of items we skip before the window begins.

WHY. The database can't act on "page 3" — it only understands "skip this many rows, then take $L$." So we must translate the human page number $p$ into a machine skip-count.

PICTURE. Look at the three windows in the figure with $L=3$:

• Page $1$ skips $0$ items → starts at index $0$.
• Page $2$ skips $3$ items → starts at index $3$.
• Page $3$ skips $6$ items → starts at index $6$.

Each new page skips one more full window than the last. Page $1$ skips $0$ windows, page $2$ skips $1$ window, page $p$ skips $(p-1)$ windows. Each skipped window is $L$ items tall, so:

$\underset{\text{items to skip}}{\underbrace{\text{offset}(p)}}=\underset{\text{how many whole pages sit above page }p}{\underbrace{(p-1)}}\times \underset{\text{items per page}}{\underbrace{L}}$

The $(p-1)$ is doing the "convert human 1-based page to zero-based count of pages above me" job; multiplying by $L$ turns "pages above" into "items above."

---

Step 4 — Which exact indices does page $p$ contain?

WHAT. The window starts at index $\text{offset}(p)=(p-1)L$ and is $L$ tall, so it covers the $L$ indices from there up to but not including $(p-1)L+L=pL$.

WHY. We use a half-open interval $[(p-1)L,pL)$ — square bracket includes the left end, round bracket excludes the right end. This is the standard slicing convention: the end of one page is exactly the start of the next, with no gap and no overlap. If we included both ends, page 1 and page 2 would share a row (duplicate). If we excluded both, one row would fall through the crack.

PICTURE. The figure shows pages $1,2,3$ with $L=3$: page 1 = indices $\{0,1,2\}$, page 2 = $\{3,4,5\}$, page 3 = $\{6,7,8\}$. The boundary line $3$ is the top of page 2 and not part of page 1 — that's the round bracket at work.

---

Step 5 — How many pages total? The ceiling appears

WHAT. Given $N$ total items and page size $L$, how many pages cover them all? We want the smallest number of windows of height $L$ that together reach every item.

WHY. If we divide $N/L$ and just chop off the decimals (that's the floor, written $\lfloor \rfloor$, "round down"), we throw away the last partial page. We must round up — that operation is the ceiling, written $\lceil \rceil$. Ceiling answers exactly the question "how many full-or-partial windows do I need to cover $N$ items?"

PICTURE. Take $N=23$, $L=10$. The figure stacks 23 items. Two full windows of 10 cover indices $0$–$19$. That leaves 3 leftover items (indices $20,21,22$) still uncovered — they demand a third page even though it's only partly full.

• $\lfloor 23/10\rfloor =2$ → would silently lose the last 3 items. ✗
• $\lceil 23/10\rceil =3$ → covers everyone. ✅

The integer trick. Real code often has no ceiling for integers, so we rewrite ceiling using floor: $\lceil \frac{N}{L}\rceil =\lfloor \frac{N+L-1}{L}\rfloor$ Adding $L-1$ before flooring nudges any nonzero remainder up into the next whole page, while a perfectly-divisible $N$ (remainder $0$) is not pushed over. Check $N=23,L=10$: $\lfloor (23+9)/10\rfloor =\lfloor 32/10\rfloor =\lfloor 3.2\rfloor =3$ ✅. Check $N=20,L=10$: $\lfloor 29/10\rfloor =2$ ✅ (exactly divisible, no extra page).

---

Step 6 — Edge & degenerate cases (never surprise the reader)

WHAT. We now walk every corner case so no input breaks the formulas.

WHY. Contracts fail at boundaries: empty tables, a last page that isn't full, asking for a page past the end, and moving data. Each deserves an explicit answer.

PICTURE. The figure shows four mini-scenarios side by side.

1. Empty table, $N=0$. $\lceil 0/L\rceil =0$ pages. A GET still succeeds with an empty list and 200 OK — not 404 (the collection exists; it's just empty).
2. Last page not full. $N=23,L=10$, page 3 is indices $[20,30)$ but only $20,21,22$ exist. The window is "up to $L$", so you return 3 items, not 10. Range stays $[(p-1)L,\min (pL,N))$.
3. Offset past the end. Ask page 5 when only 3 pages exist: offset $=(5-1)\cdot 10=40\ge 23$. The slice $[40,50)$ is empty → return an empty list with 200 OK, not an error. There simply are no rows there.
4. Moving data. Someone inserts a new item at index $0$ between your page-1 and page-2 requests. Everything shifts down by one, so the old "index 9" becomes "index 10" and you see it twice (once on page 1, again on page 2). Offset pagination is not stable under writes — for live feeds switch to cursor pagination (see Database indexing for why WHERE id > cursor stays fast).

---

The one-picture summary

The whole derivation on one axis: the stack of indexed items, the fixed-height window sliding down by $L$ each page, the offset arrow $(p-1)L$, the half-open ranges, and the ragged last page that forces the ceiling.

Recall Feynman retelling — say it in plain words

Picture users stacked in a tower, numbered from zero. A page is just a window of a fixed height $L$ that I slide down the tower. To get to page $p$, I step over all the whole windows sitting above me — there are $p-1$ of them, each $L$ tall — so I skip $(p-1)\times L$ items; that skip-count is the offset. My window then grabs the indices from where I stopped up to (not including) the next window's start, so pages tile the tower perfectly with no gaps or overlaps. To count how many pages the whole tower needs, I divide height by window size — but if there's any leftover shorter-than-$L$ bit at the bottom, I still need one more window, so I round up (the ceiling), never down. Empty tower → zero pages, and a GET still says 200 with an empty list. Ask for a window past the bottom → also empty, still 200. And if someone slips a new item in at the top while I'm reading, everything shifts and I might see a row twice — that's why live feeds use a cursor instead of an offset.

Recall

Why offset for page $p$ with size $L$? ::: $(p-1)\cdot L$ — skip the $(p-1)$ whole windows above, each $L$ tall. Which indices does page $p$ hold? ::: The half-open range $[(p-1)L,pL)$ — $L$ items, left included, right excluded. Why ceiling, not floor, for total pages? ::: A leftover partial window still needs its own page; floor would drop it. $\lceil N/L\rceil$. Integer form of the ceiling? ::: $\lfloor (N+L-1)/L\rfloor$ — the $+L-1$ pushes any nonzero remainder into the next page. What status code for an empty or out-of-range page? ::: 200 OK with an empty list — the collection exists. When does offset pagination duplicate/skip rows? ::: When the dataset changes between requests; use cursor pagination for feeds.

---

Related: HTTP protocol · Idempotency and retries · Caching and ETags · API versioning and backward compatibility · OpenAPI / Swagger · GraphQL