Link-Template general response

What it does

Link-Template extends the concept of the Link header to express relationships that need parameters rather than a single fixed URL. Where Link points to one specific resource, Link-Template provides a URI Template (per RFC 6570) — a pattern with placeholder variables the client fills in to construct the actual URL it needs, without the server having to enumerate every possible variation upfront.

This matters for APIs with parameterized lookups: instead of a server needing to list a Link for every possible user ID, order ID, or search query, it can publish one Link-Template describing the general shape, and clients construct whichever specific URL they need.

Syntax

Link-Template: <template>; rel="<relation>"; var-base="<base>"

Example:

Link-Template: https://api.example.com/users{/id}; rel="item"

The {/id} portion is a URI Template variable — a client wanting user 42 constructs https://api.example.com/users/42 by substituting the variable, following RFC 6570's templating syntax rather than any custom substitution scheme.

How it differs from Link

Link points to one concrete, already-resolvable URL:

Link: </api/users/42>; rel="self"

Link-Template points to a pattern requiring client-side substitution before use:

Link-Template: /api/users{/id}; rel="item"

The client can't fetch a Link-Template URL directly — it first has to substitute the template variables according to RFC 6570's rules, then request the resulting concrete URL.

How it's used in practice

• API discovery/hypermedia design — REST APIs following HATEOAS-style discoverability principles use Link-Template to let clients discover the shape of parameterized endpoints (item lookups, search, filtering) without hardcoding URL patterns, staying resilient if the underlying URL structure changes.
• Reducing response payload size for enumerable relationships — rather than embedding a Link for every item in a large collection, a single Link-Template describes how to construct a link to any item, which is far more compact than enumerating potentially thousands of individual links.
• Search and filter endpoint discovery — a server can advertise Link-Template: /search{?q,page}; rel="search" letting clients understand the exact expected query parameter names without needing separate documentation.

Common mistakes and gotchas

Trying to fetch a Link-Template URL directly. The template string isn't a valid, requestable URL on its own — clients must perform RFC 6570 variable substitution first. Treating it like a normal Link and fetching the raw template string will fail or return unexpected results.

Not implementing proper URI Template expansion. RFC 6570 defines a fairly rich templating syntax (simple string expansion, reserved expansion, fragment expansion, path segments, query parameters, and more) — a client-side implementation that only handles basic {variable} substitution may fail on more complex template expressions a server legitimately uses.

Assuming broad support. Link-Template is a newer, less universally adopted header than Link — many HTTP clients and tools have no built-in awareness of it at all, meaning consuming it correctly typically requires custom client-side handling rather than relying on framework support.

Real-world examples

Item lookup template:

HTTP/1.1 200 OK
Link-Template: <https://api.example.com/orders{/id}>; rel="item"

A client wanting order 789 substitutes to construct https://api.example.com/orders/789.

Search endpoint discovery:

HTTP/1.1 200 OK
Link-Template: <https://api.example.com/search{?q,limit,offset}>; rel="search"

A client can construct https://api.example.com/search?q=widgets&limit=20&offset=0 by filling in the template variables it needs.

FAQ

Do I need special tooling to use Link-Template?

You need a client-side URI Template (RFC 6570) implementation to correctly expand the template into a usable URL — most languages have a library for this, but it's not something you can handle with simple string concatenation for anything beyond the most trivial templates.

Why not just document the URL pattern separately instead of using this header?

Separate documentation works, but Link-Template makes the pattern machine-discoverable at runtime — a client (or generic API-browsing tool) can discover and construct valid URLs without a human having read separate docs first, which matters for genuinely hypermedia-driven API designs.

Is Link-Template widely supported?

Not as universally as the standard Link header — it's a comparatively newer addition to the HTTP header landscape, so expect to implement client-side handling explicitly rather than relying on broad out-of-the-box framework or tool support.

What's the relationship between Link-Template and URI Templates (RFC 6570)?

Link-Template is essentially a delivery mechanism for a URI Template — the actual templating syntax and substitution rules come entirely from RFC 6570, which Link-Template doesn't redefine, just transports as an HTTP header value.

Fun fact

URI Templates (RFC 6570) predate Link-Template by well over a decade — the templating syntax was originally designed for general-purpose use in API documentation and OpenAPI/Swagger-style specifications long before it got its own dedicated HTTP header for advertising templates directly in responses. Link-Template is essentially HTTP catching up to a pattern that had already been informally standard practice in API design for years.