Course contentsShow
← Web Development
Lesson 1511 of 2,98227. REST API Design for FrontendFree lesson

Pagination Metadata

Reading total count, page count, and navigation links from API responses.

Pagination Metadata

What you'll learn: How to extract and use total count, page count, and navigation links from paginated API responses to build complete pagination controls.

Understanding Pagination Metadata

When an API returns a paginated list, it doesn't just send you the current page's data—it also sends metadata about the pagination state. This metadata tells your frontend everything it needs to know: how many total items exist, how many pages there are, which page you're on, and often direct links to navigate to other pages.

Think of pagination metadata like the information bar at the bottom of a search engine results page: "Showing results 1-10 of 1,247" plus links to pages 1, 2, 3, etc. Without that metadata, you'd have no idea how many results exist or how to navigate beyond what you see.

Common Metadata Fields

APIs typically include metadata either in response headers or in the JSON body itself:

In the response body:

{
  "data": [...],
  "total": 1247,
  "page": 1,
  "per_page": 10,
  "total_pages": 125,
  "links": {
    "first": "/api/items?page=1",
    "next": "/api/items?page=2",
    "last": "/api/items?page=125"
  }
}

In headers (common with Link header):

X-Total-Count: 1247
X-Total-Pages: 125
Link: </api/items?page=2>; rel="next", </api/items?page=125>; rel="last"

Your frontend reads this metadata to build navigation controls, display item counts ("Showing 1-10 of 1,247"), and determine when to disable "next" or "previous" buttons.

Key Takeaway: Pagination metadata provides the total count, page count, current position, and navigation links your frontend needs to build complete, user-friendly pagination controls—always parse and use this information from API responses.