Pagination navigation
A collection endpoint can advertise the URL for the next page and the final page through Link relations.
Express.js · Module
res.links
res.links() populates the HTTP Link response header from relation names mapped to URLs. It is useful for communicating pagination or other related-resource links.
How it works
Call res.links with an object whose property names are link relations and whose values are their URLs. Express converts those entries into a Link response header, then returns the response object so response methods can be chained or followed by sending the body.
Syntax
res.links(links)Parameters
| Name | Type | Description |
|---|---|---|
links | Record<String, String> | An object whose properties, such as next and last, populate the Link response header. |
Returns
Response
Key points
- The method combines all entries into the response's Link header.
- The target header is the HTTP Link header.
- In Express 4.x, the argument is an object mapping relation names to URL strings.
- A typical use case is exposing next and last pagination URLs from an endpoint.
Common mistakes
- The object keys become relation names in the Link header, so use meaningful relation identifiers such as next and last.
Example: Add pagination links to a response
const express = require('express');
const app = express();
app.get('/users', (req, res) => {
res.links({
next: 'https://api.example.com/users?page=2',
last: 'https://api.example.com/users?page=5'
});
res.json([{ id: 1, name: 'Ada' }]);
});
app.listen(3000);Adds navigation URLs to the response's Link header before sending JSON.
When to use it
Related-resource discovery
An API can expose URLs for related resources without embedding every related object in the response body.
HTTP hypermedia metadata
A response can describe alternate or neighboring representations using named link relations.
Interview questions
QWhat does res.links do?
res.links(links) accepts a Record<String, String> and returns the Response object. It joins each supplied relation-to-URL property into the HTTP Link response header.
Follow-up: What header does a pagination example produce? It contains angle-bracketed URLs followed by rel attributes, such as <URL>; rel="next".
QHow do you use res.links for pagination?
Pass an object such as { next: '...page=2', last: '...page=5' }. Express serializes those properties into one Link header, which describes related resources or navigation targets.
Follow-up: How would you use it in a route? Call res.links before res.json or another response-ending method so the header is set before the response is sent.
QWhat are the argument and return types?
The documented 4.x method accepts a single links argument typed as Record<String, String>. The method returns Response, allowing continued use of the response object.
Follow-up: What changed in newer documentation? Later API documentation also permits each relation value to be an array of URL strings, but that is not the 4.x signature used here.
Related
res.set()res.header()res.json()res.send()