Page-Based Pagination — Simple Page Number Navigation

In this tutorial, you will learn about Page. We cover key concepts, practical examples, and best practices to help you master this topic.

Page-based pagination lets clients navigate by page number with a configurable or fixed page size, offering the simplest developer experience for paginated data access.

What You'll Learn

You will learn page-based pagination, how it differs from offset-limit, and when to use each approach.

Request Format

GET /api/users?page=3&per_page=50

Implementation

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/api/users")
async def list_users(
    page: int = Query(1, ge=1),
    per_page: int = Query(20, ge=1, le=100)
):
    offset = (page - 1) * per_page
    # Query database with LIMIT and OFFSET

Common Mistakes

1. No maximum per_page — Allowing clients to request too many records.
2. Inconsistent page size — Changing per_page between requests without notice.

What's Next

In the next lesson, you will learn cursor-based pagination for dynamic datasets.