idnits 2.17.1 draft-wilde-linkset-link-rel-01.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 (January 02, 2017) is 2670 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC6690' is defined on line 302, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) == Outdated reference: A later version (-11) exists of draft-kelly-json-hal-08 Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Wilde 3 Internet-Draft CA Technologies 4 Intended status: Informational H. Van de Sompel 5 Expires: July 6, 2017 Los Alamos National Laboratory 6 January 02, 2017 8 Linkset: A Link Relation Type for Link Sets 9 draft-wilde-linkset-link-rel-01 11 Abstract 13 This specification defines the "linkset" link relation type that can 14 be used to link to a resource that provides a set of links. 16 Note to Readers 18 Please discuss this draft on the ART mailing list 19 (). 21 Online access to all versions and files is available on GitHub 22 (). 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on July 6, 2017. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 60 3. Link Sets . . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 4. Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 4.1. Third-Party Links . . . . . . . . . . . . . . . . . . . . 3 63 4.2. Large Number of Links . . . . . . . . . . . . . . . . . . 3 64 5. Link Relation for Linking to Link Sets . . . . . . . . . . . 3 65 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 6.1. Link Set Serialized as application/link-format . . . . . 4 67 6.2. Link Set Serialized As application/hal+json . . . . . . . 6 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 69 7.1. Link Relation Type: linkset . . . . . . . . . . . . . . . 7 70 8. Security Considerations . . . . . . . . . . . . . . . . . . . 7 71 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 72 9.1. Normative References . . . . . . . . . . . . . . . . . . 7 73 9.2. Informative References . . . . . . . . . . . . . . . . . 8 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 76 1. Introduction 78 A resource typically conveys typed Web Links [RFC5988] as an inherent 79 part of the resource's representation [RFC7231], for example, using 80 the element for HTML representations or the "Link" header in 81 HTTP response headers for representations of any media type. Cases 82 exist in which providing links in a by value manner is impractical or 83 impossible. In these cases, an approach to provide links by 84 reference is desired. This specification defines the "linkset" 85 relation type that allows doing so. 87 2. Terminology 89 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 90 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 91 document are to be interpreted as described in RFC 2119 [RFC2119]. 93 3. Link Sets 95 ... 97 4. Scenarios 99 4.1. Third-Party Links 101 Cases exist in which a resource other than the responding resource is 102 better placed to provide web links. That other resource is hosted by 103 a link server that may be managed by the same custodian as the 104 responding resource or by a third party. In order for the responding 105 server to provide up-to-date links about its resource, it needs to 106 obtain them from the link server, and embed them in the resource's 107 representation prior to responding to a client. Doing so increases 108 latency, which may be unnecessary if a client is not intent on 109 consuming links. Providing links by reference, instead of by value, 110 removes this additional latency by avoiding server-to-server 111 communication required to obtain links. 113 4.2. Large Number of Links 115 When conveying links in the HTTP "Link" header, cases exist in which 116 the size of the HTTP response header becomes unpredictable. This is, 117 for example, the case when links are determined dynamically dependent 118 on a range of contextual factors. It is possible to statically 119 configure a web server to correctly handle large HTTP response 120 headers by specifying an upper boundary for their size. But, when 121 the number of links and the amount of bytes required for each is 122 unpredictable, estimating a reliable upper boundary is challenging. 123 While HTTP RFC 2616 [RFC2616] defines error codes related to excess 124 communication by the user agent ("413 Request Entity Too Large" and 125 "414 Request-URI Too Long"), no error codes are defined to indicate 126 that a response header exceeds the upper boundary that can be handled 127 by the server. As a result, applications take counter measures aimed 128 at controlling the size of the HTTP "Link" header, for example, by 129 limiting the links they provide to those with select relation types, 130 thereby limiting the value of the HTTP "Link" header to clients. 131 Providing links by reference, instead of by value, overcomes 132 challenges related to the unpredictable nature of the extent of HTTP 133 "Link" headers. 135 5. Link Relation for Linking to Link Sets 137 The "linkset" relation type can be used by a responding resource to 138 refer to another resource that provides a set of links. Typically 139 the Context IRI of these links is the URI of the responding resource 140 but links with other Context IRIs MAY be provided. 142 The media type of the link set that is accessible via the Target IRI 143 of a link with the "linkset" relation type is not constrained but the 144 representation of the link set MUST allow a user-agent to 145 unambiguously determine the Context IRI of each provided link. 147 More than one link with a "linkset" relation type MAY be provided. 148 Multiple such links can refer to the same set of links expressed 149 using different representations or to different link sets. The use 150 of a link with the "linkset" relation type does not preclude the 151 provision of links with other relation types. 153 6. Examples 155 Figure 1 shows a user agent issuing an HTTP head request against 156 resource http://example.org/resource1. 158 HEAD /resource1 HTTP/1.1 159 Host: example.org 160 Connection: close 162 Figure 1: User Agent Issues HTTP HEAD on Resource 164 Sections Section 6.1 and Section 6.2 exemplify possible responses to 165 the HTTP request of Figure 1 that include the provision of a link 166 with the "linkset" relation type, as well as a user-agent following 167 those links to retrieve a link set. 169 6.1. Link Set Serialized as application/link-format 171 Figure 2 shows the response to the HEAD request of Figure 1. The 172 response contains a "Link" header with a link that uses the "linkset" 173 relation type. It indicates that links are provided by another 174 resource http://example.com/links/http://example.org/resource, which 175 has media type application/link-format [[RFC6690]]. Using this media 176 type, links are serialized in the same manner as the payload of the 177 "Link" header, which lowers the barrier for user-agents that are 178 already able to consume HTTP links. 180 HTTP/1.1 200 OK 181 Date: Mon, 28 Nov 2016 14:37:51 GMT 182 Server: Apache-Coyote/1.1 183 Link: 184 ; rel="linkset" 185 ; type="application/link-format" 186 Content-Length: 5214 187 Content-Type: text/html;charset=utf-8 188 Connection: close 190 Figure 2: Response to HTTP HEAD on Resource 192 Figure 3 shows the user agent issuing an HTTP GET request against the 193 Target IRI of the link with the "linkset" relation type shown in 194 Figure 2. 196 GET /links/http://example.org/resource1 HTTP/1.1 197 Host: example.com 198 Accept: application/link-format 199 Connection: close 201 Figure 3: User Agent Issues HTTP GET on application/link-format Link 202 Set Resource 204 Figure 4 shows response to the HTTP GET request of Figure 3. As can 205 be seen from this example, in order to support an unambiguous 206 determination of the Context IRI of each link, an approach is taken 207 whereby an "anchor" attribute is provided for each link. For most 208 links, the Context IRI is the resource that provided the link with 209 the "linkset" relation type, namely http://example.org/resource1. 211 HTTP/1.1 200 OK 213 Date: Mon, 28 Nov 2016 14:40:02 GMT 214 Server: Apache-Coyote/1.1 215 Content-Length: 3018 216 Content-Type: application/link-format 218 219 ; rel="author" 220 ; type="application/rdf+xml" 221 ; anchor="http://example.org/resource1", 222 223 ; rel="author" 224 ; type="application/rdf+xml" 225 ; anchor="http://example.org/resource1", 226 227 ; rel="item" 228 ; type="application/pdf" 229 ; anchor="http://example.org/resource1", 230 231 ; rel="item" 232 ; type="text/html" 233 ; anchor="http://example.org/resource1", 234 235 ; rel="related" 236 ; type="application/pdf" 237 ; anchor="http://example.org/resource1/items/AF48EF.pdf", 238 ... 240 Figure 4: Response to HTTP GET on the application/link-format Link 241 Set Resource 243 6.2. Link Set Serialized As application/hal+json 245 In this example, the response to Figure 1 is the same as Figure 2 but 246 the content of the "type" attribute is application/hal+json 247 [I-D.kelly-json-hal] instead of application/link-format. Similarly, 248 the user-agent's follow-up request is the same as Figure 3 but using 249 application/hal+json in the "Accept" HTTP request header instead of 250 application/link-format. Figure 5 exemplifies a response to that 251 follow-up HTTP GET request issued against the link set resource. 253 HTTP/1.1 200 OK 254 Date: Mon, 28 Nov 2016 14:40:02 GMT 255 Server: Apache-Coyote/1.1 256 Content-Length: 2021 257 Content-Type: application/hal+json 258 Connection: close 260 ... 262 Figure 5: Response to HTTP GET on the application/link-format Link 263 Set Resource 265 7. IANA Considerations 267 The link relation type below has been registered by IANA per 268 Section 6.2.1 of RFC 5988 [RFC5988]: 270 7.1. Link Relation Type: linkset 272 Relation Name: linkset 274 Description: The Target IRI of a link with the "linkset" relation 275 type provides a set of links. 277 Reference: [[ This document ]] 279 8. Security Considerations 281 ... 283 9. References 285 9.1. Normative References 287 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 288 Requirement Levels", BCP 14, RFC 2119, 289 DOI 10.17487/RFC2119, March 1997, 290 . 292 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 293 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 294 Transfer Protocol -- HTTP/1.1", RFC 2616, 295 DOI 10.17487/RFC2616, June 1999, 296 . 298 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 299 DOI 10.17487/RFC5988, October 2010, 300 . 302 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 303 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 304 . 306 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 307 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 308 DOI 10.17487/RFC7231, June 2014, 309 . 311 9.2. Informative References 313 [I-D.kelly-json-hal] 314 Kelly, M., "JSON Hypertext Application Language", draft- 315 kelly-json-hal-08 (work in progress), May 2016. 317 Authors' Addresses 319 Erik Wilde 320 CA Technologies 322 Email: erik.wilde@dret.net 323 URI: http://dret.net/netdret/ 325 Herbert Van de Sompel 326 Los Alamos National Laboratory 328 Email: herbertv@lanl.gov 329 URI: http://public.lanl.gov/herbertv/