Page-Based Pagination
You'll learn: How to request data by page number and when this classic pagination pattern fits your application best.
What is Page-Based Pagination?
Page-based pagination divides your data into fixed-size pages identified by page numbers — exactly like a book. You request data by specifying which page you want, and the API returns that chunk along with metadata about total pages available.
This is what you see on most e-commerce sites: "Page 1 of 24" with clickable page numbers at the bottom.
How It Works
The client sends a request specifying:
page: Which page number to retrieve (usually starting at 1)pageSizeorlimit: How many items per page
GET /api/products?page=3&pageSize=20
The API response typically includes:
- The actual data array for that page
- Total number of items
- Total number of pages
- Current page number
{
"data": [...],
"page": 3,
"pageSize": 20,
"totalItems": 147,
"totalPages": 8
}
When to Use Page-Based Pagination
Best for:
- E-commerce product listings where users browse and jump to specific pages
- Search results where users want to skip ahead
- Admin panels with stable, filterable datasets
- Any UI showing page numbers or "jump to page" controls
Not ideal when:
- Data changes frequently (new items added constantly)
- Users primarily scroll continuously rather than jumping pages
- Performance matters more than user convenience (cursor-based is faster)
Analogy
Think of a library catalog system. You can ask for "books 41-60" (page 3, 20 per page) and even jump directly to page 10 to see books 181-200. The librarian can tell you exactly how many pages exist because the collection is relatively stable.
Key Takeaway: Page-based pagination is the most user-friendly pattern for browsable content with stable datasets, giving users clear navigation and the ability to jump to any page directly.