idnits 2.17.1 draft-ietf-httpapi-link-template-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (28 April 2022) is 701 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Normative reference to a draft: ref. 'HTTP' ** Obsolete normative reference: RFC 5987 (Obsoleted by RFC 8187) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Building Blocks for HTTP APIs M. Nottingham 3 Internet-Draft 28 April 2022 4 Intended status: Standards Track 5 Expires: 30 October 2022 7 The Link-Template HTTP Header Field 8 draft-ietf-httpapi-link-template-00 10 Abstract 12 This specification defines the Link-Template HTTP header field, 13 providing a means for describing the structure of a link between two 14 resources, so that new links can be generated. 16 About This Document 18 This note is to be removed before publishing as an RFC. 20 The latest revision of this draft can be found at https://ietf-wg- 21 httpapi.github.io/link-template/draft-ietf-httpapi-link- 22 template.html. Status information for this document may be found at 23 https://datatracker.ietf.org/doc/draft-ietf-httpapi-link-template/. 25 Discussion of this document takes place on the Building Blocks for 26 HTTP APIs Working Group mailing list (mailto:httpapi@ietf.org), which 27 is archived at https://mailarchive.ietf.org/arch/browse/httpapi/. 29 Source for this draft and an issue tracker can be found at 30 https://github.com/ietf-wg-httpapi/link-template. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on 30 October 2022. 49 Copyright Notice 51 Copyright (c) 2022 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 56 license-info) in effect on the date of publication of this document. 57 Please review these documents carefully, as they describe your rights 58 and restrictions with respect to this document. Code Components 59 extracted from this document must include Revised BSD License text as 60 described in Section 4.e of the Trust Legal Provisions and are 61 provided without warranty as described in the Revised BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 66 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2 67 2. The Link-Template Header Field . . . . . . . . . . . . . . . 3 68 2.1. The 'var-base' parameter . . . . . . . . . . . . . . . . 3 69 3. Security Considerations . . . . . . . . . . . . . . . . . . . 4 70 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 71 5. Normative References . . . . . . . . . . . . . . . . . . . . 4 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5 74 1. Introduction 76 [URI-TEMPLATE] defines a syntax for templates that, when expanded 77 using a set of variables, results in a URI [URI]. 79 This specification defines a HTTP header field [HTTP] for conveying 80 templates for links in the headers of a HTTP message. It is 81 complimentary to the Link header field defined in Section 3 of 82 [WEB-LINKING], which carries links directly. 84 1.1. Notational Conventions 86 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 87 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 88 "OPTIONAL" in this document are to be interpreted as described in 89 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 90 capitals, as shown here. 92 This document uses the Augmented BNF defined in [HTTP] to specify 93 valid protocol elements. Additionally, it uses the modified 94 "parameter" rule from [RFC5987] and the "URI-Template" rule from 95 [URI-TEMPLATE]. 97 2. The Link-Template Header Field 99 The Link-Template header field provides a means for serialising one 100 or more links into HTTP message metadata. It is semantically 101 equivalent to the Link header field defined in Section 3 of 102 [WEB-LINKING], except that it uses URI Templates [URI-TEMPLATE] to 103 convey the structure of links. 105 Link-Template = "Link-Template" ":" #templated-link 106 templated-link = "<" URI-Template ">" *( ";" parameter ) 108 For example: 110 Link-Template: ; rel="https://example.org/rel/user" 112 indicates that a resource with the relation type 113 "https://example.org/rel/user" can be found by interpolating the 114 "username" variable into the template given. 116 The target for the link (as defined in Section 2 of [WEB-LINKING]) is 117 the result of expanding the URI Template [URI-TEMPLATE] (being 118 converted to an absolute URI after expansion, if necessary). 120 The context, relation type and target attributes for the link are 121 determined as defined for the Link header field in Section 3 of 122 [WEB-LINKING]. 124 Parameters on a templated-link have identical semantics to those of a 125 Link header field. This includes (but is not limited to) the use of 126 the "rel" parameter to convey the relation type, the "anchor" 127 parameter to modify the context IRI, and so on. 129 Likewise, the requirements for parameters on templated-links are the 130 same as those for a Link header field; in particular, the "rel" 131 parameter MUST NOT appear more than once, and if it does, the 132 templated-link MUST be ignored by parsers. 134 This specification defines additional semantics for the "var-base" 135 parameter on templated-links; see below. 137 2.1. The 'var-base' parameter 139 When a templated-link has a 'var-base' parameter, its value conveys a 140 URI-reference that is used as a base URI for the variable names in 141 the URI template. This allows template variables to be globally 142 identified, rather than specific to the context of use. 144 Dereferencing the URI for a particular variable might lead to more 145 information about the syntax or semantics of that variable; 146 specification of particular formats for this information is out of 147 scope for this document. 149 To determine the URI for a given variable, the value given is used as 150 a base URI in reference resolution (as specified in [URI]). If the 151 resulting URI is still relative, the context of the link is used as 152 the base URI in a further resolution; see [WEB-LINKING]. 154 For example: 156 Link-Template: ; 157 rel="https://example.org/rel/widget"; 158 var-base="https://example.org/vars/" 160 indicates that a resource with the relation type 161 "https://example.org/rel/widget" can be found by interpolating the 162 "https://example.org/vars/widget_id" variable into the template 163 given. 165 If the current context of the message that the header appears within 166 is "https://example.org/", the same information could be conveyed by 167 this header field: 169 Link-Template: ; 170 rel="https://example.org/rel/widget"; 171 var-base="/vars/" 173 3. Security Considerations 175 The security consideration for the Link header field in [WEB-LINKING] 176 and those for URI Templates [URI-TEMPLATE] both apply. 178 4. IANA Considerations 180 This specification enters the "Link-Template" into the Hypertext 181 Transfer Protocol (HTTP) Field Name Registry. 183 Field Name: Link-Template 184 Status: permanent 185 Specification document: [this document] 187 5. Normative References 189 [HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 190 Semantics", Work in Progress, Internet-Draft, draft-ietf- 191 httpbis-semantics-19, 12 September 2021, 192 . 195 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 196 Requirement Levels", BCP 14, RFC 2119, 197 DOI 10.17487/RFC2119, March 1997, 198 . 200 [RFC5987] Reschke, J., "Character Set and Language Encoding for 201 Hypertext Transfer Protocol (HTTP) Header Field 202 Parameters", RFC 5987, DOI 10.17487/RFC5987, August 2010, 203 . 205 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 206 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 207 May 2017, . 209 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 210 Resource Identifier (URI): Generic Syntax", STD 66, 211 RFC 3986, DOI 10.17487/RFC3986, January 2005, 212 . 214 [URI-TEMPLATE] 215 Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 216 and D. Orchard, "URI Template", RFC 6570, 217 DOI 10.17487/RFC6570, March 2012, 218 . 220 [WEB-LINKING] 221 Nottingham, M., "Web Linking", RFC 8288, 222 DOI 10.17487/RFC8288, October 2017, 223 . 225 Author's Address 227 Mark Nottingham 228 Prahran 229 Australia 230 Email: mnot@mnot.net 231 URI: https://www.mnot.net/