Symfony 8.2 Adds Link-Template Headers and JSON Link Sets
- Javier Eguiluz
- 737 reads
Symfony 8.2 adds support for templated HTTP links and JSON link sets, helping API teams publish and consume resource relationships.

Symfony 8.2 fills two gaps in its WebLink component: applications can now send URI templates in a dedicated HTTP header, and publish collections of links as standalone documents. For API teams, the change makes relationships and resource patterns easier to expose to clients, while keeping the existing handling of concrete links intact.

The component already supports the Link header, which follows RFC 8288. Applications often use it to hint that a browser should preload or prefetch an asset. APIs can use the same mechanism to point clients to related resources. Symfony 8.2 extends that foundation with the Link-Template header, defined by RFC 9652, and link sets, defined by RFC 9264.
Templates get their own response header
A conventional Link header describes a specific target, such as /users/42. That doesn’t cover a relationship whose URL depends on a value the client supplies. A URI template such as /users/{id} communicates the pattern without pretending the server already knows which user the client wants.
Symfony’s Link class could represent templated links before 8.2, but the response had nowhere to carry them: they were dropped. The new behavior sorts links by target. Concrete URLs continue to appear in Link; templates are emitted in Link-Template.
$this->addLink($request, new Link('preload', '/app.css')
->withAttribute('as', 'style'));
$this->addLink($request, new Link('item', '/users/{id}'));
return $this->render('user/index.html.twig');In this example, the response retains a Link header for the stylesheet and adds a Link-Template header for the user resource pattern. Existing code that adds ordinary links doesn’t need to change. Teams that previously attempted to attach templates should check the response headers after upgrading, since those links can now reach clients instead of disappearing.
For clients consuming an API, the new LinkTemplateHeaderParser turns header values into familiar Link objects. The parsed object exposes the template through getHref(), identifies it with isTemplated(), and makes its relation available through getRels(). That keeps application code working with the component’s link model instead of parsing header syntax itself.
Link sets move relationships into documents
Headers are useful for a handful of links attached to a response. They become less convenient when an API needs to expose a larger catalog, or when clients should be able to discover relationships without requesting each linked resource first. A link set addresses that case by collecting links in a standalone document. RFC 9727, for example, describes a link set used to list a host’s APIs at /.well-known/api-catalog.
RFC 9264 defines two document formats. The application/linkset format uses syntax familiar from the Link header, so Symfony’s existing serializer and parser can handle it. For the JSON form, application/linkset+json, Symfony 8.2 adds JsonLinksetSerializer and JsonLinksetParser.
The serializer accepts a collection of Link objects and an optional bitmask of json_encode() options. A controller can return the result with the JSON link set media type. In the resulting document, links are grouped first by their context, expressed through the anchor attribute, and then by relation type. That structure lets a client distinguish, for example, API documentation from an API description even when both refer to the same service.
$links = [
new Link(Link::REL_SERVICE_DESC, 'https://example.com/api/books/openapi.yaml')
->withAttribute('anchor', 'https://example.com/api/books')
->withAttribute('type', 'application/yaml'),
new Link(Link::REL_SERVICE_DOC, 'https://example.com/docs/books')
->withAttribute('anchor', 'https://example.com/api/books')
->withAttribute('type', 'text/html'),
];
$document = $serializer->serialize($links, \JSON_UNESCAPED_SLASHES);On the receiving side, JsonLinksetParser returns links that expose their target, relation, and attributes through the same API used for other parsed links. The anchor and type metadata therefore remain available to client code, rather than being trapped in a format-specific JSON structure.
Discovery requires one more link
Publishing a link set doesn’t automatically tell clients where to find it. Symfony’s example advertises the document from a resource response with a link whose relation is linkset, pointing to the set’s URL and declaring its media type as application/linkset+json. This gives clients a standard discovery step while leaving the set’s contents available from a separate endpoint.
The practical gain in 8.2 is focused: templates no longer vanish when applications send them, and API relationships can be serialized or parsed as a document. Teams adopting either feature will still need to decide which links belong in response headers and which merit a separately published set, then ensure their clients understand the relevant header or media type. Those decisions depend on the API’s shape; Symfony supplies the building blocks, while the next useful signal will be how broadly client tooling handles these formats.