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 instead of relying on the server to enumerate every possible link.

Table of Contents

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/"

Quoted strings, not angle brackets

Link-Template mirrors Link semantics while abandoning the older syntax: the value is a structured-field list of strings, so a template travels in quotation marks rather than the angle brackets Link uses. Writing </users/{id}> in the header is the natural mistake and the wrong one, since the angle-bracket form belongs to the other field.

Templates follow the URI Template standard at every level, expansion operators included, and the anchor parameter accepts a template of its own. The one genuinely new idea is var-base, which turns template variable names into global identifiers by prefixing a base URI, so {widget_id} resolves to an address a client dereferences to learn what the variable means, a step toward self-describing APIs.

Adoption is the honest caveat: the field is standards-track and registered, and as of 2026 no mainstream server, client, or framework ships support. The header is a design available to build on rather than one to expect in traffic.

See also

Last updated: August 17, 2026