Course contentsShow
← Software Engineering
Lesson 786 of 1,93324. REST API DesignFree lesson

Pagination Metadata and Links

Returning pagination metadata like total count, page info, and HATEOAS-style next/previous links in responses.

Pagination Metadata and Links

You'll learn how to include essential pagination information and navigation links in API responses to guide clients through multi-page data.

The Core Idea

When your API returns paginated data, clients need more than just the current page's items—they need context: How many items exist in total? Which page are they viewing? How do they get to the next page? Pagination metadata provides these answers directly in your response, while navigation links (HATEOAS-style) give clients ready-made URLs to fetch adjacent pages.

Think of it like a library catalog: you're not just handed one page of book listings, you're also told "This is page 5 of 20 total pages" and given buttons for "Previous," "Next," and "Last page."

What to Include

A well-designed paginated response typically provides:

Metadata:

  • total_count or total: Total number of items across all pages
  • page or current_page: Which page you're viewing
  • page_size or per_page: Items per page
  • total_pages: Total pages available (calculated from total and page size)

HATEOAS Links:

  • self: URL for the current page
  • next: URL for the next page (if available)
  • previous or prev: URL for the previous page (if available)
  • first: URL for the first page
  • last: URL for the last page

Example response structure:

{
  "data": [ /* array of items */ ],
  "pagination": {
    "total": 247,
    "page": 3,
    "page_size": 20,
    "total_pages": 13
  },
  "links": {
    "self": "/api/products?page=3",
    "next": "/api/products?page=4",
    "prev": "/api/products?page=2",
    "first": "/api/products?page=1",
    "last": "/api/products?page=13"
  }
}

Key Takeaway: Always return pagination metadata and navigation links in paginated responses—they turn your API from a data dump into a navigable, self-documenting interface that clients can explore without guesswork.