Pagination Metadata — Response Format Conventions

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

Pagination metadata informs clients about the current page position, total available records, navigation options, and whether more data is available.

Standard Response Formats

// Offset pagination metadata
{
  "data": [],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 95,
    "pages": 5,
    "hasNext": true,
    "hasPrev": true
  }
}

// Cursor pagination metadata
{
  "data": [],
  "pagination": {
    "limit": 20,
    "nextCursor": "base64encodedstring",
    "hasMore": true
  }
}

Common Patterns

Use consistent field names across all endpoints. Include pagination in a nested object separate from data. Use hasNext/hasPrev booleans instead of forcing clients to calculate from other fields.

Common Mistakes

1. Missing hasNext/hasPrev — Forcing clients to calculate navigation.
2. Inconsistent field names — page vs page_number vs current_page across endpoints.
3. No pagination on filtered results — Pagination should reflect filtered counts.

Practice Questions

1. What fields should offset pagination metadata include?
2. What fields should cursor pagination metadata include?
3. Why include hasNext instead of calculating it?

What's Next

In the next lesson, you will learn Link headers for pagination.