Page Based

title: "Page-Based Pagination — Simple Page and Limit Parameters" description: "Page-based pagination uses page number and page size parameters for intuitive navigation, built on offset-limit but presented with user-friendly page numbers." date: 2026-06-28 lastmod: 2026-06-28 weight: 13 tags: [apis, pagination] }

Page-based pagination is a variant of offset-limit that exposes page and limit (or per_page) parameters, translating to SQL OFFSET and LIMIT behind the scenes.

What You'll Learn

• Page-based pagination API design
• Calculating total pages from count
• Navigation links (first, prev, next, last)

Why It Matters

Page-based pagination is the most developer-friendly pattern. It's intuitive: "Give me page 3 of users."

Code Examples

# Page-based pagination
@app.route('/users')
def list_users():
    page = request.args.get('page', 1, type=int)
    per_page = request.args.get('per_page', 20, type=int)
    per_page = min(per_page, 100)  # cap
    offset = (page - 1) * per_page

    users = db.get_users(limit=per_page, offset=offset)
    total = db.count_users()
    total_pages = (total + per_page - 1) // per_page

    return jsonify({
        "data": users,
        "page": page,
        "per_page": per_page,
        "total": total,
        "total_pages": total_pages,
        "links": {
            "first": f"/users?page=1&per_page={per_page}",
            "prev": f"/users?page={page-1}&per_page={per_page}" if page > 1 else None,
            "next": f"/users?page={page+1}&per_page={per_page}" if page < total_pages else None,
            "last": f"/users?page={total_pages}&per_page={per_page}"
        }
    })

// Express page-based pagination
app.get('/products', paginate, (req, res) => {
  const { page, limit, offset } = req.pagination;
  // Handler uses req.pagination for queries
});

Common Mistakes

1. Page Starting at 0

Most developers expect page=1. If using 0-indexed pages, document clearly.

2. No per_page Default

Always provide a sensible default (20-50).

3. Inconsistent Parameter Names

Use either page/limit, page/per_page, or page/page_size consistently.

4. No Next/Prev Links

Include navigation URLs so clients don't construct them.

5. Wrong Total Pages Calculation

total_pages = Math.ceil(total / per_page), not total / per_page.

Practice Questions

1. What parameters does page-based pagination use?
2. How do you calculate total pages?
3. Why should page numbers start at 1?
4. What is the purpose of navigation links?
5. How do you prevent abuse with large page sizes?

Answers:

1. page (page number) and limit or per_page (items per page).
2. Math.ceil(total / per_page).
3. Most developers expect page 1 as the first page.
4. They let clients navigate without constructing URLs.
5. Cap per_page at a maximum value (e.g., 100).

Challenge: Build page-based pagination with full navigation links (first, prev, next, last) and test the edge case when the requested page exceeds the total.

FAQ