idnits 2.17.1 draft-wilde-linkset-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 (September 6, 2017) is 2424 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC6690' is defined on line 809, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5987 (Obsoleted by RFC 8187) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) Summary: 4 errors (**), 0 flaws (~~), 2 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: March 10, 2018 Los Alamos National Laboratory 6 September 6, 2017 8 Linkset: Media Types and a Link Relation Type for Link Sets 9 draft-wilde-linkset-01 11 Abstract 13 This specification defines two media types and a link relation type 14 for sets of links. The media types can be used to represents links 15 in a standalone fashion, in one case in the native format used in the 16 HTTP Link header, and in the other case in a JSON-based format. The 17 link relation can be used to reference these kind of standalone link 18 sets, so that a resource can indicate that additional links putting 19 it into context are available someplace else. One typical scenario 20 is when the number of links to put in an HTTP Link header field 21 becomes too big, and thus these links should be provided by a 22 distinct resource. 24 Note to Readers 26 Please discuss this draft on the ART mailing list 27 (). 29 Online access to all versions and files is available on GitHub 30 (). 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 March 10, 2018. 49 Copyright Notice 51 Copyright (c) 2017 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 56 (https://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 68 3. Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . 3 69 3.1. Third-Party Links . . . . . . . . . . . . . . . . . . . . 4 70 3.2. Challenges Writing to HTTP Link Header Field . . . . . . 4 71 3.3. Large Number of Links . . . . . . . . . . . . . . . . . . 5 72 4. Document Formats for Link Sets . . . . . . . . . . . . . . . 5 73 4.1. HTTP Link Document Format: application/linkset . . . . . 6 74 4.2. JSON Document Format: application/linkset+json . . . . . 6 75 4.2.1. Link Sets . . . . . . . . . . . . . . . . . . . . . . 6 76 4.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 6 77 4.2.3. Link Target Attributes . . . . . . . . . . . . . . . 8 78 4.2.4. Extension Target Attributes . . . . . . . . . . . . . 10 79 5. The "linkset" Relation Type for Linking to Link Sets . . . . 10 80 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 11 81 6.1. Links Provided in the Header of the Link Set Resource . . 11 82 6.2. Links Provided in the Body of the Link Set Resource, 83 Link Set Serialized as application/linkset+json . . . . . 13 84 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 85 7.1. Link Relation Type: linkset . . . . . . . . . . . . . . . 15 86 7.2. Media Type: application/linkset . . . . . . . . . . . . . 16 87 7.2.1. IANA Considerations . . . . . . . . . . . . . . . . . 16 88 7.3. Media Type: application/linkset+json . . . . . . . . . . 17 89 8. Security Considerations . . . . . . . . . . . . . . . . . . . 18 90 9. Normative References . . . . . . . . . . . . . . . . . . . . 18 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 93 1. Introduction 95 Resources on the Web often convey typed Web Links 96 [I-D.nottingham-rfc5988bis] as a part of resource representations, 97 for example, using the element for HTML representations, or 98 the "Link" header field in HTTP response headers for representations 99 of any media type. In some cases, however, providing links by value 100 is impractical or impossible. In these cases, an approach to provide 101 links by reference (instead of by value) can solve the problem. 103 To that end, this specification defines two document formats and 104 associated media types to represent a set of links. It also defines 105 the "linkset" relation type that a resource can use to support 106 discovery of another resource that conveys links in which the former 107 resource participates. 109 2. Terminology 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in RFC 2119 [RFC2119]. 115 This specification uses the terms "link context" and "link target" as 116 defined in [I-D.nottingham-rfc5988bis]. (These terms respectively 117 correspond with "Context IRI" and "Target IRI" as used in RFC 5988 118 [RFC5988]). Although defined as IRIs, in common scenarios they are 119 also URIs. 121 Additionally, this specification uses the following terms for types 122 of resources involved in providing links by reference: 124 o A "link set resource" is a resource that conveys a set of links. 125 Section 4 defines two representations for a set of links, based on 126 the abstract link model defined in [I-D.nottingham-rfc5988bis]. 128 o An "origin resource" is a resource that participates in one or 129 more links provided by a link set resource. An origin resource 130 can support discovery of an associated link set resource by using 131 the relation type defined in Section 5. As such, from the 132 perspective of the origin resource, the links conveyed by the link 133 set resource are provided by reference. 135 3. Scenarios 137 The following sections outline some scenarios in which it is useful 138 to have the ability to separate resources from the links that pertain 139 to them. 141 These are all scenarios in which providing links by reference is 142 advantageous or necessary. It is important to keep in mind that, 143 when providing some links by reference, some/other links can still be 144 provided by value. 146 3.1. Third-Party Links 148 In some cases, it is useful that links pertaining to an origin 149 resource are provided by a server other than the one that hosts the 150 origin resource. For example, this allows: 152 o Providing links in which the origin resource is involved not just 153 as link context but also as link target. 155 o Providing links pertaining to the origin resource that the server 156 hosting that resource is not aware of. 158 o External management of links pertaining to the origin resource in 159 a special-purpose link management service. 161 In such cases, a third-party link set resource provides links 162 pertaining to the origin resource. This link set resource may be 163 managed by the same custodian as the origin resource, or by a third 164 party. 166 In order for the server hosting the origin resource to provide an up- 167 to-date and complete set of links in which the origin resource 168 participates, the server would need to obtain the links from the link 169 set resource, and embed them in the origin resource's representations 170 prior to responding to a client. Doing so would increase latency and 171 load, which may be unnecessary if a client is not intent on consuming 172 these links. Providing links by reference, instead of by value, 173 removes the server-to-server communication and resulting overhead 174 required to obtain links. Instead, the consumer of the origin 175 resource can decide if they need the additional links as context for 176 the resource. 178 3.2. Challenges Writing to HTTP Link Header Field 180 In some cases, it is not straightforward to write links to the HTTP 181 Link header field from an application. This can, for example, be the 182 case because not all required link information is available to the 183 application or because the application does not have the capability 184 to directly write HTTP headers. In such cases, providing links by 185 reference can be a solution because a link to a link set resource 186 associated with an origin resource can typically be added by means of 187 a web server rewrite rule that leverages the resource's URI. 189 3.3. Large Number of Links 191 When conveying links in the HTTP "Link" header, it is possible for 192 the size of the HTTP response header to become unpredictable. This 193 can be the case when links are determined dynamically dependent on a 194 range of contextual factors. It is possible to statically configure 195 a web server to correctly handle large HTTP response headers by 196 specifying an upper boundary for their size. But when the number of 197 links is unpredictable, estimating a reliable upper boundary is 198 challenging. 200 HTTP [RFC7231] defines error codes related to excess communication by 201 the user agent ("413 Request Entity Too Large" and "414 Request-URI 202 Too Long"), but no specific error codes are defined to indicate that 203 response header content exceeds the upper boundary that can be 204 handled by the server, and thus it has been truncated. As a result, 205 applications take counter measures aimed at controlling the size of 206 the HTTP "Link" header, for example by limiting the links they 207 provide to those with select relation types, thereby limiting the 208 value of the HTTP "Link" header to clients. Providing links by 209 reference, instead of by value, overcomes challenges related to the 210 unpredictable nature of the extent of HTTP "Link" headers. 212 In more extreme scenarios it is conceivable that the number of links 213 pertaining to the origin resource becomes so large that the response 214 from the associated link set resource becomes too large. This could 215 be the case for highly popular origin resources, when the link set 216 includes links in which the origin resource participates as both link 217 context and link target. In such cases, the link set resource could 218 deliver responses incrementally, for example, using a paged resource 219 model that clients can consume as required. 221 4. Document Formats for Link Sets 223 Link set resources can be represented by serializations that support 224 conveying both link contexts and link targets. This section 225 specifies two document formats based on the abstract model specified 226 in Section 2 of [I-D.nottingham-rfc5988bis] that defines a link as 227 consisting of a "link context", a "link relation type", a "link 228 target", and optional "target attributes". In those terms, a link 229 set resource is a resource that conveys a collection of one or more 230 such links. 232 The format defined in Section 4.1 is identical to the payload of the 233 HTTP Link header as specified in [I-D.nottingham-rfc5988bis]. The 234 format defined in Section 4.2 is based on JSON and thus does not have 235 the character encoding limitations of HTTP header fields. 237 4.1. HTTP Link Document Format: application/linkset 239 This document format is identical to the payload of the HTTP Link 240 header. It is defined in Section 3 of [I-D.nottingham-rfc5988bis], 241 more specifically by its ABNF production rule for "Link" and 242 subsequent ones. The assigned media type for this format is 243 "application/linkset". 245 4.2. JSON Document Format: application/linkset+json 247 This document format is based on the native Link header field 248 representation defined by [I-D.nottingham-rfc5988bis], but uses JSON 249 [RFC7159] as the syntax to represent the information contained in the 250 native format. It is described in this section. The assigned media 251 type for this format is "application/linkset+json". 253 4.2.1. Link Sets 255 In the JSON representation of a link set: 257 o A link set MUST be represented as a JSON array. 259 o A distinct JSON object - the "link object" - in this array MUST be 260 used to represent an individual link or multiple links that have 261 the same link context and link target. (see Section 4.2.2). 263 o Implementations MUST wrap link objects in an array, even if the 264 link set contains only one link. 266 o Implementations MUST NOT include any members other than link 267 objects in the array that represents a link set. 269 4.2.2. Links 271 In the JSON representation, individual links (as well as multiple 272 links that have the same link context and link target) are 273 represented by a JSON object, the link object. A link object adheres 274 to the following rules: 276 o Each link object MUST have an "href" member with a value that 277 represents the link target. 279 o Each link object MAY have an "anchor" member with a value that 280 represents the link context. If this member is not provided, the 281 link context is the link set resource. 283 o The value of both the "href" and "anchor" members MUST be a URI- 284 reference as defined in Section 4.1 of [RFC3986]. Note that for 285 relative references, the baseURI is the URI of the link set 286 resource. 288 o Each link object MUST have a "rel" or "rev" member (with the 289 latter one deprecated) with a value that represents one or more 290 link relation types, represented as an array of strings. The 291 value of each "rel"/"rev" link relation type MUST either be a 292 registered relation type or an extension relation type (URI), as 293 described in Sections 2.1.1 and 2.1.2 of 294 [I-D.nottingham-rfc5988bis], respectively. 296 o Each link object MAY have additional members representing target 297 attributes (see Section 4.2.3). 299 The following example of a JSON-serialized link set represents one 300 link with the core components of a link: link context, link relation 301 type, and link target. 303 [ { "href" : "http://example.com/foo", 304 "anchor" : "http://example.net/bar", 305 "rel" : [ "next" ] } ] 307 The following example of a JSON-serialized link set represents two 308 links with the core components of a link: link context, link relation 309 type, and link target. The syntax of this example takes advantage of 310 the fact that multiple relation types can be used in one link object 311 to represent multiple links that have the same link context and link 312 target. 314 [ { "href" : "http://example.com/foo", 315 "anchor" : "http://example.net/bar", 316 "rel " : [ "next" , "http://example.net/linkrel" ] } ] 318 The previous example is equivalent to the following one, which does 319 not use the syntax shortcut and therefore represents the two links 320 individually. 322 [ { "href" : "http://example.com/foo", 323 "anchor" : "http://example.net/bar", 324 "rel" : [ "next" ] }, 325 { "href" : "http://example.com/foo", 326 "anchor" : "http://example.net/bar", 327 "rel" : [ "http://example.net/linkrel" ] } ] 329 4.2.3. Link Target Attributes 331 In many cases, a link is further qualified by target attributes, 332 either defined by the serialization of [I-D.nottingham-rfc5988bis] or 333 extension attributes defined and used by communities. 335 4.2.3.1. JSON Representation of RFC 5988bis Target Attributes 337 RFC 5988bis defines the following target attributes that may be used 338 to annotate links: "hreflang", "media", "title", "title*", and 339 "type". These target attributes follow different occurrence and 340 value patterns and MUST be handled in the JSON representation as 341 follows: 343 o "hreflang": The optional and repeatable "hreflang" target 344 attribute MUST be represented by an array (even if there only is 345 one value to be represented), and each value in that array MUST be 346 a string - representing one value of the "hreflang" target 347 attributes for a link - which follows the same model as in the 348 [I-D.nottingham-rfc5988bis] syntax. 350 o "media": The optional and not repeatable "media" target attribute 351 MUST be represented by a "media" member in the link object, and 352 its value MUST be a string that follows the same model as in the 353 [I-D.nottingham-rfc5988bis] syntax. 355 o "type": The optional and not repeatable "type" target attribute 356 MUST be represented by a "type" member in the link object, and its 357 value MUST be a string that follows the same model as in the 358 [I-D.nottingham-rfc5988bis] syntax. 360 o "title": The optional and not repeatable "title" target attribute 361 MUST be represented by a "title" member in the link object, and 362 its value MUST be a string that follows the same model as in the 363 [I-D.nottingham-rfc5988bis] syntax. 365 o "title*": The optional and not repeatable "title*" target 366 attribute is motivated by character encoding and language issues 367 and follows the model defined in [RFC5987]. The details of the 368 JSON representation that applies to title* are described in 369 Section 4.2.3.2. 371 The following example illustrates how the repeatable "hreflang" and 372 the not repeatable "type" target attributes are represented in a link 373 object. 375 [ { "href" : "http://example.com/foo", 376 "anchor" : "http://example.net/bar", 377 "rel" : [ "next" ] , 378 "hreflang" : [ "en" , "de" ] , 379 "type" : "text/html" } ] 381 4.2.3.2. Internationalized Target Attributes for a Link 383 In addition to the target attributes described in Section 4.2.3, 384 [I-D.nottingham-rfc5988bis] also supports attributes that follow the 385 content model of [RFC5987]. In [I-D.nottingham-rfc5988bis], these 386 target attributes are recognizable by the use of a trailing asterisk 387 in the attribute name, such as "title*". The content model of 388 [RFC5987] uses a string-based microsyntax that represents the 389 character encoding, an optional language tag, and the escaped 390 attribute value encoded according to the specified character 391 encoding. 393 The JSON serialization for these attributes is as follows: 395 o Internationalized target attributes use the attribute name 396 (including the *) as their name. 398 o The character encoding information as prescribed by [RFC5987] is 399 not preserved; instead, the attribute value is represented in the 400 character encoding used for the JSON link set. 402 o The attribute value is an array that contains one or more arrays. 403 In each of these arrays, the first value is a string representing 404 the attribute value (in its unescaped version), and the optional 405 second array value is a language tag [RFC5646] associated with 406 that attribute value. 408 The following example illustrates how the "title*" target attribute 409 defined by [I-D.nottingham-rfc5988bis] is represented in a link 410 object. 412 [ { "href" : "http://example.com/foo", 413 "anchor" : "http://example.net/bar", 414 "rel" : [ "next" ] , 415 "title*" : [ [ "nachstes Kapitel", "de" ] ] } ] 417 The above example assumes that the german title contains an umlaut 418 character (which in the native syntax would be encoded as title*=UTF- 419 8'de'n%c3%a4chstes%20Kapitel), which gets encoded in its unescaped 420 form (but not shown here due to the limitations of RFC publication) 421 in the JSON representation. Implementations MUST properly decode/ 422 encode RFC 5987 style target attributes when transcoding between the 423 native and the JSON syntax. 425 4.2.4. Extension Target Attributes 427 Extension target attributes are attributes that are not defined by 428 RFC 5988bis (as listed in Section 4.2.3.1), but are nevertheless used 429 to qualify links. They can be defined by communities in any way 430 deemed necessary, and it is up to them to make sure their usage is 431 understood by target applications. However, lacking standardization, 432 there is no interoperable understanding of these extension 433 attributes. One important consequence is that their cardinality is 434 unknown to generic applications. Therefore, in the JSON 435 serialization, all extension target attributes are treated as 436 repeatable: 438 o Extension target attributes use the attribute name (including the 439 *, if applicable) as their name. 441 o The value of an extension attribute MUST be represented by an 442 array (even if there only is one value to be represented). 444 o If the extension attribute does not have a name with a trailing 445 asterisk, then each value in that array MUST be a string that 446 represents one value of the extension target attribute. 448 o If the extension attribute has a name with a trailing asterisk (it 449 follows the content model of [RFC5987]), then each value in that 450 array MUST be an array. The value of each array MUST be 451 structured as described in Section 4.2.3.2. 453 5. The "linkset" Relation Type for Linking to Link Sets 455 The target of a link with the "linkset" relation type - the link set 456 resource - provides a set of links, including links in which the link 457 context - the origin resource - participates. 459 A link with the "linkset" relation type MAY be provided in the header 460 and/or the body of the origin resource's representation. It may also 461 be discovered by other means, such as through client-side 462 information. 464 More than one link with a "linkset" relation type MAY be provided. 465 Multiple such links can refer to the same set of links expressed 466 using different representations, or to different sets of links 467 (potentially provided by different services). 469 The use of a link with the "linkset" relation type does not preclude 470 the provision of links with other relation types, i.e. the origin 471 resource can provide typed links other than a "linkset" link. 472 Therefore, the effective set of links pertaining to the origin 473 resource is the union of the links that the resource itself provides, 474 and of all links - provided by the link set resource - in which it 475 participates. 477 The link set resource MAY provide the links that pertain to the 478 origin resource in its HTTP response header and/or body. 480 In common scenarios (the origin resource is distinct from the link 481 set resource), it is essential for link set representations to make 482 the URI of the origin resource explicit for those links in which the 483 origin resource acts as link context. 485 A user agent that follows a "linkset" link from an origin resource 486 MUST be aware that the link set resource can provide links in which 487 the origin resource does not participate and MAY decide to ignore 488 those links. 490 There is no constraint on the target URI of a link with the "linkset" 491 relation type; designing and using these URIs is left to the 492 discretion of implementers. 494 If an origin resource provides a "linkset" link pointing at a link 495 set resource, and that link set resource provides a "linkset" link in 496 turn, then this latter link points at links pertaining to the link 497 set resource. This means that in the context of the latter link, the 498 link set resource is an origin resource. This means that linkset 499 relations are not transitive, and it is up to a client to decide 500 whether they follow "nested chains" of "linkset" links or not. 502 6. Examples 504 Sections Section 6.1 and Section 6.2 show examples whereby the link 505 set resource provides links pertaining to the origin resource, in its 506 response header and body, respectively. 508 6.1. Links Provided in the Header of the Link Set Resource 510 Figure 1 shows a client issuing an HTTP head request against origin 511 resource http://example.org/resource1. 513 HEAD /resource1 HTTP/1.1 514 Host: example.org 515 Connection: close 517 Figure 1: Client HTTP HEAD Request 519 Figure 2 shows the response to the HEAD request of Figure 1. The 520 response contains a Link header with a link that uses the "linkset" 521 relation type. It indicates that links pertaining to the origin 522 resource are provided by link set resource http://example.com/ 523 links?uri=http%3A%2F%2Fexample.org%2Fresource. 525 HTTP/1.1 200 OK 526 Date: Mon, 28 Nov 2016 14:37:51 GMT 527 Server: Apache-Coyote/1.1 528 Link: 529 ; rel="linkset" 530 ; type="text/html" 531 Content-Length: 5214 532 Content-Type: text/html;charset=utf-8 533 Connection: close 535 Figure 2: Response to HTTP HEAD on Origin Resource 537 While in this example the URI of the link set resource uses a pattern 538 that represents the URI of the origin resource, this is opaque to the 539 client, which simply follows target URI to retrieving the link set 540 resource. 542 Figure 3 shows the client issuing an HTTP GET request against the 543 link set resource provided in Figure 2. 545 GET /links?uri=http%3A%2F%2Fexample.org%2Fresource HTTP/1.1 546 Host: example.com 547 Connection: close 549 Figure 3: Client HTTP GET against the Link Set Resource 551 Figure 4 shows the response headers to the HTTP GET request of 552 Figure 3. The links pertaining to the origin resource are provided 553 in the Link response header of the link set resource. As can be 554 seen, in order to support an unambiguous determination of the link 555 context of each link, the "anchor" attribute is always provided. 556 Note that most, but not all, links have the origin resource as link 557 context (anchor). 559 HTTP/1.1 200 OK 560 Date: Mon, 28 Nov 2016 14:40:02 GMT 561 Server: Apache-Coyote/1.1 562 Link: 563 ; rel="author" 564 ; type="application/rdf+xml" 565 ; anchor="http://example.org/resource1", 566 567 ; rel="author" 568 ; type="application/rdf+xml" 569 ; anchor="http://example.org/resource1", 570 571 ; rel="item" 572 ; type="application/pdf" 573 ; anchor="http://example.org/resource1", 574 575 ; rel="item" 576 ; type="text/html" 577 ; anchor="http://example.org/resource1", 578 579 ; rel="related" 580 ; type="application/pdf" 581 ; anchor="http://example.org/resource1/items/AF48EF.pdf" 582 Content-Type: text/html 583 Content-Length: 3018 585 Figure 4: Response to HTTP GET against the Link Set Resource 587 6.2. Links Provided in the Body of the Link Set Resource, Link Set 588 Serialized as application/linkset+json 590 Figure 5 is an example of a client issuing an HTTP head request 591 against origin resource http://example.org/article?id=10.1371/ 592 journal.pone.0167475 594 HEAD article?id=10.1371/journal.pone.0167475 HTTP/1.1 595 Host: example.org 596 Connection: close 598 Figure 5: Client HTTP HEAD Request 600 Figure 6 shows the response to the HEAD request of Figure 5. The 601 response contains a Link header with a link that has the "linkset" 602 relation type. It indicates that links pertaining to the origin 603 resource are provided by link set resource 604 http://example.com/links/10.1371/journal.pone.0167475, which provides 605 a representation with media type application/linkset+json. 607 HTTP/1.1 200 OK 608 Date: Mon, 28 Nov 2016 14:37:51 GMT 609 Server: Apache-Coyote/1.1 610 Link: 611 ; rel="linkset" 612 ; type="application/linkset+json" 613 Content-Length: 236 614 Content-Type: text/html;charset=utf-8 615 Connection: close 617 Figure 6: Response to HTTP HEAD on Origin Resource 619 In this example, the URI of the linkset resource does not directly 620 represent the URI of the origin resource anymore. There still is an 621 association possible through the use of a URI pattern that is 622 includes identifying information. But as in the example above, the 623 URI of the link set resource is opaque to the client that simply 624 accesses the URI to retrieve the link set resource. 626 Figure 7 shows the client issuing an HTTP GET request against the 627 link set resource provided in Figure 6. 629 GET /links/10.1371/journal.pone.0167475 HTTP/1.1 630 Host: example.com 631 Accept: application/linkset+json 632 Connection: close 634 Figure 7: Client HTTP GET against the Link Set Resource 636 Figure 8 shows the response headers to the HTTP GET request of 637 Figure 7. The links pertaining to the origin resource are provided 638 in the response body of the link set resource and are serialized 639 according to the media type application/linkset+json. 641 HTTP/1.1 200 OK 642 Date: Mon, 28 Nov 2016 14:40:02 GMT 643 Server: Apache-Coyote/1.1 644 Content-Type: application/linkset+json 645 Content-Length: 794 647 [{"href":"http://authors.example.net/johndoe", 648 "anchor":"http://example.org/article?id=10.1371/journal.pone.0167475", 649 "rel":["author"],"type":"application/rdf+xml"}, 650 {"href":"http://authors.example.net/janedoe", 651 "anchor":"http://example.org/article?id=10.1371/journal.pone.0167475", 652 "rel":["author"],"type":"application/rdf+xml"}, 653 {"href":"http://example.org/resource1/items/AF48EF.pdf", 654 "anchor":"http://example.org/article?id=10.1371/journal.pone.0167475", 655 "rel":["item"],"type":"text/html"}, 656 {"href":"http://example.org/resource1/items/CB63DA.html", 657 "anchor":"http://example.org/article?id=10.1371/journal.pone.0167475", 658 "rel":"[item"],"type":"application/pdf"}, 659 {"href":"http://example.net/resource41/", 660 "anchor":"http://example.org/resource1/items/AF48EF.pdf", 661 "rel":["related"],"type":"application/pdf"}] 663 Figure 8: Response to HTTP GET against the Link Set Resource 665 If Figure 6 would have provided a link to a link set with media type 666 application/linkset, and if the client would have requested that link 667 set, then the body of the response would have been similar to 668 Figure 8. But it would have had application/linkset as Content-Type, 669 the payload of the HTTP Link header of Figure 4 as body, and an 670 accordingly adjusted value for Content-Length. 672 7. IANA Considerations 674 7.1. Link Relation Type: linkset 676 The link relation type below has been registered by IANA per 677 Section 6.2.1 of Web Linking [I-D.nottingham-rfc5988bis]: 679 Relation Name: linkset 681 Description: The Target IRI of a link with the "linkset" relation 682 type provides a set of links that pertain to the Context IRI of 683 the link. 685 Reference: [[ This document ]] 687 7.2. Media Type: application/linkset 689 7.2.1. IANA Considerations 691 The Internet media type [RFC6838] for a natively encoded link set is 692 application/linkset. 694 Type name: application 696 Subtype name: linkset 698 Required parameters: none 700 Optional parameters: none 702 Encoding considerations: ... 704 Security considerations: ... 706 Interoperability considerations: ... 708 Published specification: [[ This document ]] 710 Applications that use this media type: ... 712 Additional information: 714 Magic number(s): N/A 716 File extension(s): This media type does not propose a specific 717 extension. 719 Macintosh file type code(s): TEXT 721 Person & email address to contact for further information: Herbert 722 Van de Sompel 724 Intended usage: COMMON 726 Restrictions on usage: none 728 Author: Herbert Van de Sompel 730 Change controller: IETF 732 7.3. Media Type: application/linkset+json 734 The Internet media type [RFC6838] for a JSON-encoded link set is 735 application/linkset+json. 737 Type name: application 739 Subtype name: linkset+json 741 Required parameters: none 743 Optional parameters: none 745 Encoding considerations: ... 747 Security considerations: ... 749 Interoperability considerations: ... 751 Published specification: [[ This document ]] 753 Applications that use this media type: ... 755 Additional information: 757 Magic number(s): N/A 759 File extension(s): JSON documents often use ".json" as the file 760 extension, and this media type does not propose a specific 761 extension other than this generic one. 763 Macintosh file type code(s): TEXT 765 Person & email address to contact for further information: Herbert 766 Van de Sompel 768 Intended usage: COMMON 770 Restrictions on usage: none 772 Author: Herbert Van de Sompel 774 Change controller: IETF 776 8. Security Considerations 778 ... 780 9. Normative References 782 [I-D.nottingham-rfc5988bis] 783 Nottingham, M., "Web Linking", draft-nottingham- 784 rfc5988bis-08 (work in progress), August 2017. 786 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 787 Requirement Levels", BCP 14, RFC 2119, 788 DOI 10.17487/RFC2119, March 1997, 789 . 791 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 792 Resource Identifier (URI): Generic Syntax", STD 66, 793 RFC 3986, DOI 10.17487/RFC3986, January 2005, 794 . 796 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 797 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 798 September 2009, . 800 [RFC5987] Reschke, J., "Character Set and Language Encoding for 801 Hypertext Transfer Protocol (HTTP) Header Field 802 Parameters", RFC 5987, DOI 10.17487/RFC5987, August 2010, 803 . 805 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 806 DOI 10.17487/RFC5988, October 2010, 807 . 809 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 810 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 811 . 813 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 814 Specifications and Registration Procedures", BCP 13, 815 RFC 6838, DOI 10.17487/RFC6838, January 2013, 816 . 818 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 819 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 820 2014, . 822 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 823 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 824 DOI 10.17487/RFC7231, June 2014, 825 . 827 [W3C.REC-html401-19991224] 828 Rivoal, F., "Media Queries", World Wide Web 829 Consortium Recommendation REC-css3-mediaqueries-20120619, 830 June 2012. 832 Authors' Addresses 834 Erik Wilde 835 CA Technologies 837 Email: erik.wilde@dret.net 838 URI: http://dret.net/netdret/ 840 Herbert Van de Sompel 841 Los Alamos National Laboratory 843 Email: herbertv@lanl.gov 844 URI: http://public.lanl.gov/herbertv/