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_countortotal: Total number of items across all pagespageorcurrent_page: Which page you're viewingpage_sizeorper_page: Items per pagetotal_pages: Total pages available (calculated from total and page size)
HATEOAS Links:
self: URL for the current pagenext: URL for the next page (if available)previousorprev: URL for the previous page (if available)first: URL for the first pagelast: 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.