Course contentsShow
← System Design
Lesson 1891 of 1,91945. API Design and VersioningFree lesson

Pagination Metadata and Links

Returning total counts, page info, and next/prev links to help clients navigate result sets.

Pagination Metadata and Links

What you'll learn: How to include helpful context in paginated responses so clients can easily navigate through large result sets.


Returning data alone isn't enough—clients need context to understand where they are in the result set and how to request more. Pagination metadata provides information like total counts, page numbers, and navigational links that make your API intuitive and self-documenting.

Why Metadata Matters

Imagine reading a book with no page numbers or table of contents. You'd never know how much content remains or how to jump to a specific section. API responses face the same challenge. Metadata answers critical questions:

  • How many total results exist?
  • Which page am I viewing?
  • Are there more results available?
  • How do I fetch the next/previous page?

Common Metadata Fields

Include these fields alongside your data array:

  • total: Total number of items across all pages
  • page: Current page number (offset-based)
  • per_page or page_size: Items returned per page
  • has_more or has_next_page: Boolean indicating if more data exists
  • next_cursor / prev_cursor: Opaque tokens for cursor-based pagination

Hypermedia Links (HATEOAS)

Instead of forcing clients to construct URLs manually, include ready-to-use links:

{
  "data": [...],
  "pagination": {
    "total": 1523,
    "page": 3,
    "per_page": 50,
    "total_pages": 31
  },
  "links": {
    "self": "/api/users?page=3&per_page=50",
    "next": "/api/users?page=4&per_page=50",
    "prev": "/api/users?page=2&per_page=50",
    "first": "/api/users?page=1&per_page=50",
    "last": "/api/users?page=31&per_page=50"
  }
}

This approach reduces client-side logic and prevents URL construction errors.

Key Takeaway: Pagination metadata and hypermedia links transform raw data into navigable result sets, providing clients with the context and tools they need to efficiently traverse large collections without guesswork.