idnits 2.17.1 draft-nottingham-link-template-02.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 (June 19, 2017) is 2502 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) ** Obsolete normative reference: RFC 5987 (Obsoleted by RFC 8187) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft June 19, 2017 4 Intended status: Standards Track 5 Expires: December 21, 2017 7 The Link-Template HTTP Header Field 8 draft-nottingham-link-template-02 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 Note to Readers 18 The issues list can be found at https://github.com/mnot/I-D/labels/ 19 link-template . 21 The most recent (often, unpublished) draft is at 22 https://mnot.github.io/I-D/link-template/ . 24 Recent changes are listed at https://github.com/mnot/I-D/commits/gh- 25 pages/link-template . 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on December 21, 2017. 44 Copyright Notice 46 Copyright (c) 2017 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 62 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2 63 2. The Link-Template Header Field . . . . . . . . . . . . . . . 2 64 2.1. The 'var-base' parameter . . . . . . . . . . . . . . . . 3 65 3. Security Considerations . . . . . . . . . . . . . . . . . . . 4 66 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 67 5. Normative References . . . . . . . . . . . . . . . . . . . . 4 68 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5 70 1. Introduction 72 [RFC6570] defines a syntax for templates that, when expanded using a 73 set of variables, results in a URI [RFC3986]. 75 This specification defines a HTTP header field for conveying 76 templates for links in the headers of a HTTP message. It is 77 complimentary to the Link header field [RFC5988], which carries links 78 directly. 80 1.1. Notational Conventions 82 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 83 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 84 document are to be interpreted as described in [RFC2119]. 86 This document uses the Augmented BNF defined in [RFC7230] to specify 87 valid protocol elements. Additionally, it uses the modified 88 "parameter" rule from [RFC5987], and the "URI-Template" rule from 89 [RFC6570]. 91 2. The Link-Template Header Field 93 The Link-Template entity-header field provides a means for 94 serialising one or more links into HTTP headers. It is semantically 95 equivalent to the Link header field [RFC5988], except that it uses 96 URI Templates [RFC6570] to convey the structure of links. 98 Link-Template = "Link-Template" ":" #linkt-value 99 linkt-value = "<" URI-Template ">" *( ";" parameter ) 101 For example: 103 Link-Template: ; rel="http://example.org/rel/user" 105 indicates that a resource with the relation type 106 "http://example.org/rel/user" can be found by interpolating the 107 "username" variable into the template given. 109 The target for the link (as defined by [RFC5988]) is the result of 110 expanding the URI Template [RFC6570] (being converted to an absolute 111 URI after expansion, if necessary). 113 The context, relation type and target attributes for the link are 114 determined as defined for the Link header field in [RFC5988]. 116 The parameters on a linkt-value have identical semantics to those of 117 a Link header field [RFC5988]. This includes (but is not limited to) 118 the use of the "rel" parameter to convey the relation type, the 119 "anchor" parameter to modify the context IRI, and so on. 121 Likewise, the requirements for parameters on linkt-values are the 122 same as those for a Link header field; in particular, the "rel" 123 parameter MUST NOT appear more than once, and if it does, the linkt- 124 value MUST be ignored by parsers. 126 This specification defines additional semantics for the "var-base" 127 parameter on linkt-values; see below. 129 2.1. The 'var-base' parameter 131 When a linkt-value has a 'var-base' parameter, its value conveys a 132 URI-reference that is used as a base URI for the variable names in 133 the URI template. 135 This mechanism allows template variables to be globally identified, 136 rather than specific to the context of use. Dereferencing the URI 137 for a particular variable might lead to more information about the 138 syntax or semantics of that variable; specification of particular 139 formats for this information is out of scope for this document. 141 To determine the URI for a given variable, the value given is used as 142 a base URI in reference resolution (as specified in [RFC3986]). If 143 the resulting URI is still relative, the context of the link is used 144 as the base URI in a further resolution; see [RFC5988]. 146 For example: 148 Link-Template: ; 149 rel="http://example.org/rel/widget"; 150 var-base="http://example.org/vars/" 152 indicates that a resource with the relation type 153 "http://example.org/rel/widget" can be found by interpolating the 154 "http://example.org/vars/widget_id" variable into the template given. 156 If the current context of the message that the header appears within 157 is "http://example.org/", the same information could be conveyed by 158 this header field: 160 Link-Template: ; 161 rel="http://example.org/rel/widget"; 162 var-base="/vars/" 164 3. Security Considerations 166 The security consideration for the Link header field in [RFC5988] and 167 those for URI Templates [RFC6570] both apply. 169 4. IANA Considerations 171 This specification enters the "Link-Template" into the registry of 172 Permanent Message Header Field Names. 174 Header Field Name: Link-Template 175 Protocol: http 176 Status: 177 Reference: [this document] 179 5. Normative References 181 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 182 Requirement Levels", BCP 14, RFC 2119, 183 DOI 10.17487/RFC2119, March 1997, 184 . 186 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 187 Resource Identifier (URI): Generic Syntax", STD 66, 188 RFC 3986, DOI 10.17487/RFC3986, January 2005, 189 . 191 [RFC5987] Reschke, J., "Character Set and Language Encoding for 192 Hypertext Transfer Protocol (HTTP) Header Field 193 Parameters", RFC 5987, DOI 10.17487/RFC5987, August 2010, 194 . 196 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 197 DOI 10.17487/RFC5988, October 2010, 198 . 200 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 201 and D. Orchard, "URI Template", RFC 6570, 202 DOI 10.17487/RFC6570, March 2012, 203 . 205 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 206 Protocol (HTTP/1.1): Message Syntax and Routing", 207 RFC 7230, DOI 10.17487/RFC7230, June 2014, 208 . 210 Author's Address 212 Mark Nottingham 214 EMail: mnot@mnot.net 215 URI: https://www.mnot.net/