RFC 9652

The Link-Template HTTP Header Field

📅 published September 2024, from ietf

Request for Comments 9652 ✨: The Link-Template HTTP Header Field

Okay bestie, so this is an IETF Standards Track doc 💅 by Mark Nottingham, published September 2024, and it's part of the Internet Standards family 🌈. It doesn't obsolete anything and doesn't update anything either, so it's a brand-new vibe 🦋. The ISSN is 2070-1721 💜.

Abstract 🎀

Basically, this spec adds the Link-Template HTTP header field, which lets you describe the shape of a link between two resources so new links can get generated on the fly 🧚. Iconic, right? 😭

Status of This Memo 📜

This one is an Internet Standards Track document 👑. The IETF made it, it's got consensus from the community, it went through public review, and the IESG approved it for publication. If you want more on Internet Standards, check out Section 2 of RFC 7841 🫶. Current status, errata, and feedback info live at https://www.rfc-editor.org/info/rfc9652 💖.

Copyright Notice 🔒

Copyright is (c) 2024 IETF Trust and the document authors, all rights reserved 🌸. It's subject to BCP 78 and the IETF Trust's Legal Provisions (https://trustee.ietf.org/license-info) as of publication. Read those carefully, bestie, since they spell out your rights 🙈. Any Code Components you pull out of this doc have to include Revised BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty per that same license ✨.

Table of Contents 🗺️

1. Introduction
- 1.1. Notational Conventions
2. The Link-Template Header Field
- 2.1. The 'var-base' Parameter
3. Security Considerations
4. IANA Considerations
5. Normative References
Author's Address

1. Introduction 🌸

So [URI-TEMPLATE] defines a syntax for templates. When you expand one with a set of variables, you get a URI [URI] 🦋.

This spec defines an HTTP header field [HTTP] for carrying templates for links in HTTP message headers 💅. It's the bestie of the Link header field from Section 3 of [WEB-LINKING], which carries links directly 🫶.

1.1. Notational Conventions 📝

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

This spec borrows these terms from [STRUCTURED-FIELDS]: List, String, Display String, and Parameter 🎀.

2. The Link-Template Header Field 💖

The Link-Template header field is a Structured Field [STRUCTURED-FIELDS] that serializes one or more links into HTTP message metadata ✨. It's semantically the same as the Link header field from Section 3 of [WEB-LINKING], except the link target and link anchor can contain URI Templates [URI-TEMPLATE] 🧚.

The Link-Template field's value is a List of Strings (see [STRUCTURED-FIELDS]). Each String holds a URI Template and can have Parameters carrying metadata for that template 🌈.

For example:

Link-Template: "/{username}"; rel="item"

This means a resource with the relation type "item" for a given "username" can be found by expanding the "username" variable into the template 🫶.

The link target (see Section 2 of [WEB-LINKING]) is figured out by expanding the template and turning it into an absolute URI, if needed 🦋.

The link context and link relation type (as defined in Section 2 of [WEB-LINKING]) ride along in the 'anchor' and 'rel' Parameters, same as the Link header field in Section 3 of [WEB-LINKING] 💅. Their values MUST be Strings.

However, the 'anchor' Parameter MAY contain a URI Template 💜. For example:

Link-Template: "/books/{book_id}/author";
               rel="author"; anchor="#{book_id}"

So here, you can find the author link for a particular book in a list of books just by following the link template 📚.

This spec adds extra semantics for the 'var-base' Parameter on templated links; see Section 2.1 🌸.

The link's target attributes (as defined in Section 2.2 of [WEB-LINKING]) are carried in other Parameters, kind of like the Link header field 🎀. These Parameter values MUST be Strings, unless they contain non-ASCII characters, in which case they MUST be Display Strings 🙈. Heads up: some target attribute names won't serialize as Structured Field Parameter keys (see Section 3.1.2 of [STRUCTURED-FIELDS]) 😭.

For example:

Link-Template: "/author"; rel="author";
               title=%"Bj%c3%b6rn J%c3%a4rnsida"

Implementations MUST support all levels of template defined by [URI-TEMPLATE] in the link String and the 'anchor' Parameter 🔥.

2.1. The 'var-base' Parameter 🧚‍♀️

When a templated link has a 'var-base' Parameter, its value is a URI-reference used as a base URI for the variable names in the URI Template 💖. This makes template variables globally identified, instead of tied to one specific context 🌍.

Dereferencing the URI for a particular variable might lead to more info about the syntax or semantics of that variable. Specifying formats for that info is out of scope for this document 🙈.

To work out the URI for a given variable, the value is used as a base URI in reference resolution (as specified in [URI]) 🦋. If the result is still relative, the link's context is used as the base URI in another resolution; see [WEB-LINKING] 💅.

For example:

Link-Template: "/widgets/{widget_id}";
               rel="https://example.org/rel/widget";
               var-base="https://example.org/vars/"

This means a resource with the relation type "https://example.org/rel/widget" can be found by expanding the "https://example.org/vars/widget_id" variable into the template 💜.

If the current context of the message the header appears in is "https://example.org/", you could convey the same info with this header field:

Link-Template: "/widgets/{widget_id}";
               rel="https://example.org/rel/widget";
               var-base="/vars/"

3. Security Considerations 🚨

Okay, this part is serious bestie 😭. The security considerations for the Link header field in [WEB-LINKING] and for URI Templates [URI-TEMPLATE] both apply 💀.

Target attributes carried in Display Strings can be vulnerable to a whole bunch of attacks 🙈. See [UNICODE-SECURITY] for advice on handling them 🛡️. This spec doesn't give specific advice, since there are lots of possible use cases for those attributes ✨.

4. IANA Considerations 🌷

This spec adds the "Link-Template" field name to the "Hypertext Transfer Protocol (HTTP) Field Name Registry" 💖.

              +===============+===========+===============+
              | Field Name    | Status    | Reference     |
              +===============+===========+===============+
              | Link-Template | Permanent | This document |
              +---------------+-----------+---------------+

Table 1 🍓

5. Normative References 📚

[HTTP]     Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
           Ed., "HTTP Semantics", STD 97, RFC 9110,
           DOI 10.17487/RFC9110, June 2022,
           <https://www.rfc-editor.org/info/rfc9110>.

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <https://www.rfc-editor.org/info/rfc2119>.

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
           May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[STRUCTURED-FIELDS]
           Nottingham, M. and P-H. Kamp, "Structured Field Values for
           HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024,
           <https://www.rfc-editor.org/info/rfc9651>.

[UNICODE-SECURITY]
           Davis, M. and M. Suignard, "Unicode Security
           Considerations", Unicode Technical Report #16, 19
           September 2014, <https://www.unicode.org/reports/tr36/>.
           Latest version available at
           <https://www.unicode.org/reports/tr36/>.

[URI]      Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
           Resource Identifier (URI): Generic Syntax", STD 66,
           RFC 3986, DOI 10.17487/RFC3986, January 2005,
           <https://www.rfc-editor.org/info/rfc3986>.

[URI-TEMPLATE]
           Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
           and D. Orchard, "URI Template", RFC 6570,
           DOI 10.17487/RFC6570, March 2012,
           <https://www.rfc-editor.org/info/rfc6570>.

[WEB-LINKING]
           Nottingham, M., "Web Linking", RFC 8288,
           DOI 10.17487/RFC8288, October 2017,
           <https://www.rfc-editor.org/info/rfc8288>.

Author's Address 💌

Mark Nottingham Prahran Australia Email: mnot@mnot.net URI: https://www.mnot.net/

📦 where this page comes from

ietf: rfc9652 2024-09
💖 girlified by claude-haiku-5-5 on 2026-10-19: a language model's rewrite of the original, under its terms