Link Header Pagination — REST API Pagination Header Implementation Errors

Overview

Fix Link header pagination errors in REST APIs including malformed Link headers, missing rel values, and client parsing failures for paginated responses.

Key Details

• Link headers provide pagination URLs for REST APIs following RFC 8288 (Web Linking)
• Standard rel values are: first, prev, next, last — indicating pagination directions
• GitHub API popularized this pattern: Link: <url>; rel="next", <url>; rel="last"
• Link headers keep pagination metadata in headers rather than the response body
• Parsing Link headers requires handling URL encoding, quoted strings, and multiple values

Common Causes

• Link header format not following RFC 8288 — missing angle brackets around URLs or quotes around rel values
• URL parameters in Link header not properly encoded (& characters in URLs)
• Client not parsing Link headers and instead hard-coding pagination logic
• Server not including Link headers for the last page, confusing client pagination logic

Steps

1. 1Format Link headers correctly: Link: <https://api.example.com/items?page=2>; rel="next", <https://api.example.com/items?page=5>; rel="last"
2. 2URL-encode any special characters in the Link header URLs
3. 3Include all four rel values (first, prev, next, last) where applicable — omit prev on page 1 and next on the last page
4. 4Use a Link header parsing library in your client (parse-link-header for Node.js, or regex for simple cases)
5. 5Also include pagination metadata in the response body (total_count, page, per_page) for convenience

Tags

More in 2xx Success

Frequently Asked Questions