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.

Table of Contents

Usage
Directives
- rel
- var-base
Example
Takeaway
See also

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 communicates the structure of a collection or set of related resources without enumerating every possible URI.

The header value is a Structured Fields List of Strings. Each string contains a URI Template following the syntax defined in the URI Template specification. 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, and both the target URI and anchor are able to contain template expressions.

Common use cases include documenting API endpoint patterns, providing collection navigation structures, and describing parameterized resource relationships where listing every possible link is impractical.

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.

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.