diff options
Diffstat (limited to 'doc/rfc/rfc9652.txt')
| -rw-r--r-- | doc/rfc/rfc9652.txt | 247 |
1 files changed, 247 insertions, 0 deletions
diff --git a/doc/rfc/rfc9652.txt b/doc/rfc/rfc9652.txt new file mode 100644 index 0000000..1dc6bf1 --- /dev/null +++ b/doc/rfc/rfc9652.txt @@ -0,0 +1,247 @@ + + + + +Internet Engineering Task Force (IETF) M. Nottingham +Request for Comments: 9652 September 2024 +Category: Standards Track +ISSN: 2070-1721 + + + The Link-Template HTTP Header Field + +Abstract + + This specification defines the Link-Template HTTP header field, + providing a means for describing the structure of a link between two + resources so that new links can be generated. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9652. + +Copyright Notice + + Copyright (c) 2024 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (https://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Revised BSD License text as described in Section 4.e of the + Trust Legal Provisions and are provided without warranty as described + in the Revised BSD 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 + + [URI-TEMPLATE] defines a syntax for templates that, when expanded + using a set of variables, results in a URI [URI]. + + This specification defines a HTTP header field [HTTP] for conveying + templates for links in the headers of a HTTP message. It is + complimentary to the Link header field defined in 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 specification uses the following 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 is semantically equivalent to the Link header + field defined in Section 3 of [WEB-LINKING], except that the link + target and link anchor can contain URI Templates [URI-TEMPLATE]. + + The Link-template header field's value is a List of Strings (see + [STRUCTURED-FIELDS]). Each String contains a URI Template and can + have Parameters that carry metadata associated with that template. + + For example: + + Link-Template: "/{username}"; rel="item" + + indicates that a resource with the relation type "item" for a given + "username" can be found by expanding the "username" variable into the + template given. + + The link target (see Section 2 of [WEB-LINKING]) is determined by + expanding the template and converting it to an absolute URI (if + necessary). + + The link context and link relation type for the link (as defined in + Section 2 of [WEB-LINKING]) are conveyed using the 'anchor' and 'rel' + Parameters, as they are for 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}" + + Here, the link to the author for a particular book in a list of books + can be found by following the link template. + + This specification defines additional 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 conveyed using other Parameters, in a manner + similar to the Link header field. These Parameter values MUST be + Strings, unless they contain non-ASCII characters, in which case they + MUST be Display Strings. Note that some target attribute names will + not 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 conveys a + URI-reference that is used as a base URI for the variable names in + the URI Template. This allows template variables to be globally + identified, rather than specific to the context of use. + + Dereferencing the URI for a particular variable might lead to more + information about the syntax or semantics of that variable; + specification of particular formats for this information is out of + scope for this document. + + To determine the URI for a given variable, the value given is used as + a base URI in reference resolution (as specified in [URI]). If the + resulting URI is still relative, the context of the link is used as + the base URI in a further resolution; see [WEB-LINKING]. + + For example: + + Link-Template: "/widgets/{widget_id}"; + rel="https://example.org/rel/widget"; + var-base="https://example.org/vars/" + + indicates that 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 + given. + + If the current context of the message that the header appears within + is "https://example.org/", the same information could be conveyed by + this header field: + + Link-Template: "/widgets/{widget_id}"; + rel="https://example.org/rel/widget"; + var-base="/vars/" + +3. Security Considerations + + The security considerations for the Link header field in + [WEB-LINKING] and those for URI Templates [URI-TEMPLATE] apply. + + Target attributes that are conveyed via Display Strings can be + vulnerable to a wide variety of attacks. See [UNICODE-SECURITY] for + advice regarding their handling. Specific advice is not given by + this specification since there are a variety of potential use cases + for such attributes. + +4. IANA Considerations + + This specification enters the "Link-Template" field name into 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/ |