Link-Template
The HTTP Link-Template response header describes the structure of a link using URI Template syntax, allowing clients to generate new URIs by expanding template variables.
Usage
The Link header carries complete, ready-to-use URIs for related resources. The Link-Template header extends this concept by providing templated URIs where variable placeholders get replaced with specific values. This approach is useful when the server wants to communicate the structure of a collection or set of related resources without enumerating every possible URI.
Template variables appear in braces, like
{widget_id} or {page}, and clients expand these templates by
substituting actual values. The header supports the same link relation
types and parameters as Link, but the target URI and anchor
contain template expressions instead of complete URIs.
Common use cases include documenting API endpoint patterns, providing collection navigation structures, and describing parameterized resource relationships where listing every possible link is impractical. The client reads the template, understands the variable structure, and generates specific URIs as needed without additional server requests.
Directives
rel
The rel parameter specifies the relationship between the current
resource and the target described by the template. Standard link
relation types include next, prev, item, collection, or
custom relations identified by URIs.
var-base
The var-base parameter provides a base URI for resolving variable
definitions and metadata. This optional parameter helps clients
understand what values are valid for template variables.
Example
A collection resource returns a Link-Template header describing how
to construct URIs for individual items. The {widget_id} variable
represents the unique identifier for each widget in the collection.
Link-Template: </widgets/{widget_id}>; rel="item"
The client expands this template by substituting specific widget IDs,
generating URIs like /widgets/42 or /widgets/abc-123 without
needing the server to enumerate every widget in the collection.
A paginated API describes its pagination structure through a template.
The {page} and {per_page} variables let clients construct requests
for any page offset and size.
Link-Template: </api/items?page={page}&per_page={per_page}>; rel="collection"
An API documentation endpoint provides a template with a base URI for variable definitions, indicating where clients learn about valid parameter values.
Link-Template: </docs/{section}>; rel="help"; var-base="https://example.re/vars/"
Takeaway
The Link-Template response header communicates URI structures using URI Template syntax, enabling clients to generate resource links by expanding template variables.