api-pagination

SKILL.md

API Pagination

Table of Contents

Overview

When to Use

Quick Start

Reference Guides

Best Practices

Overview

Implement scalable pagination strategies for handling large datasets with efficient querying, navigation, and performance optimization.

When to Use

Returning large collections of resources

Implementing search results pagination

Building infinite scroll interfaces

Optimizing large dataset queries

Managing memory in client applications

Improving API response times

Quick Start

Minimal working example:

// Node.js offset/limit implementation
app.get('/api/users', async (req, res) => {
  const page = parseInt(req.query.page) || 1;
  const limit = Math.min(parseInt(req.query.limit) || 20, 100); // Max 100
  const offset = (page - 1) * limit;

  try {
    const [users, total] = await Promise.all([
      User.find()
        .skip(offset)
        .limit(limit)
        .select('id email firstName lastName createdAt'),
      User.countDocuments()
    ]);

    const totalPages = Math.ceil(total / limit);

    res.json({
      data: users,
      pagination: {
        page,
        limit,
        total,
        totalPages,
        hasNext: page < totalPages,
// ... (see reference guides for full implementation)

Reference Guides

Detailed implementations in the references/ directory:

Guide
Contents

Offset/Limit Pagination
Offset/Limit Pagination

Cursor-Based Pagination
Cursor-Based Pagination

Keyset Pagination
Keyset Pagination

Search Pagination
Search Pagination

Pagination Response Formats
Pagination Response Formats

Python Pagination (SQLAlchemy)
Python Pagination (SQLAlchemy)

Best Practices

✅ DO

Use cursor pagination for large datasets

Set reasonable maximum limits (e.g., 100)

Include total count when feasible

Provide navigation links

Document pagination strategy

Use indexed fields for sorting

Cache pagination results when appropriate

Handle edge cases (empty results)

Implement consistent pagination formats

Use keyset for extremely large datasets

❌ DON'T

Use offset with billions of rows

Allow unlimited page sizes

Count rows for every request

Paginate without sorting

Change sort order mid-pagination

Use deep pagination without cursor

Skip pagination for large datasets

Expose database pagination directly

Mix pagination strategies

Ignore performance implications

1d:[