idnits 2.17.1 draft-nottingham-link-hint-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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [3], [4], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 4, 2020) is 1512 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 515 -- Looks like a reference, but probably isn't: '2' on line 517 -- Looks like a reference, but probably isn't: '3' on line 519 -- Looks like a reference, but probably isn't: '4' on line 521 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7233 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) Summary: 7 errors (**), 0 flaws (~~), 1 warning (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft March 4, 2020 4 Intended status: Informational 5 Expires: September 5, 2020 7 HTTP Link Hints 8 draft-nottingham-link-hint-02 10 Abstract 12 This memo specifies "HTTP Link Hints", a mechanism for annotating Web 13 links to HTTP(S) resources with information that otherwise might be 14 discovered by interacting with them. 16 Note to Readers 18 _RFC EDITOR: please remove this section before publication_ 20 The issues list for this draft can be found at 21 https://github.com/mnot/I-D/labels/link-hint [1]. 23 The most recent (often, unpublished) draft is at 24 https://mnot.github.io/I-D/link-hint/ [2]. 26 Recent changes are listed at https://github.com/mnot/I-D/commits/gh- 27 pages/link-hint [3]. 29 See also the draft's current status in the IETF datatracker, at 30 https://datatracker.ietf.org/doc/draft-nottingham-link-hint/ [4]. 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 September 5, 2020. 49 Copyright Notice 51 Copyright (c) 2020 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 67 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 68 2. HTTP Link Hints . . . . . . . . . . . . . . . . . . . . . . . 4 69 3. Pre-Defined HTTP Link Hints . . . . . . . . . . . . . . . . . 4 70 3.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 5 71 3.2. formats . . . . . . . . . . . . . . . . . . . . . . . . . 5 72 3.3. links . . . . . . . . . . . . . . . . . . . . . . . . . . 5 73 3.4. accept-post . . . . . . . . . . . . . . . . . . . . . . . 6 74 3.5. accept-patch . . . . . . . . . . . . . . . . . . . . . . 7 75 3.6. accept-ranges . . . . . . . . . . . . . . . . . . . . . . 7 76 3.7. accept-prefer . . . . . . . . . . . . . . . . . . . . . . 7 77 3.8. precondition-req . . . . . . . . . . . . . . . . . . . . 8 78 3.9. auth-schemes . . . . . . . . . . . . . . . . . . . . . . 8 79 3.10. status . . . . . . . . . . . . . . . . . . . . . . . . . 9 80 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 81 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 82 5.1. HTTP Link Hint Registry . . . . . . . . . . . . . . . . . 9 83 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 84 6.1. Normative References . . . . . . . . . . . . . . . . . . 10 85 6.2. Informative References . . . . . . . . . . . . . . . . . 11 86 6.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 12 87 Appendix A. Representing Link Hints in Link Headers . . . . . . 12 88 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 13 89 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 91 1. Introduction 93 HTTP [RFC7230] clients can discover a variety of information about a 94 resource by interacting with it. For example, the methods supported 95 can be learned through the Allow response header field, and the need 96 for authentication is conveyed with a 401 Authentication Required 97 status code. 99 Often, it can be beneficial to know this information before 100 interacting with the resource; not only can such knowledge save time 101 (through reduced round trips), but it can also affect the choices 102 available to the code or user driving the interaction. 104 For example, a user interface that presents the data from an HTTP- 105 based API might need to know which resources the user has write 106 access to, so that it can present the appropriate interface. 108 This specification defines a vocabulary of "HTTP link hints" that 109 allow such metadata about HTTP resources to be attached to Web links 110 [RFC8288], thereby making it available before the link is followed. 111 It also establishes a registry for future hints. 113 Hints are just that - they are not a "contract", and are to only be 114 taken as advisory. The runtime behaviour of the resource always 115 overrides hinted information. 117 For example, a client might receive a hint that the PUT method is 118 allowed on all "widget" resources. This means that generally, the 119 client can PUT to them, but a specific resource might reject a PUT 120 based upon access control or other considerations. 122 More fine-grained information might also be gathered by interacting 123 with the resource (e.g., via a GET), or by another resource 124 "containing" it (such as a "widgets" collection) or describing it 125 (e.g., one linked to it with a "describedby" link relation). 127 There is not a single way to carry hints in a link; rather, it is 128 expected that this will be done by individual link serialisations 129 (see [RFC8288], Section 3.4.1). However, Appendix A does recommend 130 how to include link hints in the existing Link HTTP header field. 132 1.1. Notational Conventions 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 136 "OPTIONAL" in this document are to be interpreted as described in BCP 137 14 [RFC2119] [RFC8174] when, and only when, they appear in all 138 capitals, as shown here. 140 2. HTTP Link Hints 142 A HTTP link hint is a (key, value) tuple that describes the target 143 resource of a Web link [RFC8288], or the link itself. The value's 144 canonical form is a JSON [RFC8259] data structure specific to that 145 hint. 147 Typically, link hints are serialised in links as target attributes 148 ([RFC8288], Section 3.4.1). 150 In JSON-based formats, this can be achieved by simply serialising 151 link hints as an object; for example: 153 { 154 "_links": { 155 "self": { 156 "href": "/orders/523", 157 "hints": { 158 "allow": ["GET", "POST"], 159 "accept-post": { 160 "application/example+json": 161 {} 162 } 163 } 164 } 165 } 166 } 168 In other link formats, this requires a mapping from the canonical 169 JSON data model. One such mapping is described in Appendix A for the 170 Link HTTP header field. 172 The information in a link hint SHOULD NOT be considered valid for 173 longer than the freshness lifetime ([RFC7234], Section 4.2) of the 174 representation that the link occurred within, and in some cases, it 175 might be valid for a considerably shorter period. 177 Likewise, the information in a link hint is specific to the link it 178 is attached to. This means that if a representation is specific to a 179 particular user, the hints on links in that representation are also 180 specific to that user. 182 3. Pre-Defined HTTP Link Hints 183 3.1. allow 185 o Hint Name: allow 187 o Description: Hints the HTTP methods that can be used to interact 188 with the target resource; equivalent to the Allow HTTP response 189 header. 191 o Content Model: array (of strings) 193 o Specification: [this document] 195 Content MUST be an array of strings, containing HTTP methods 196 ([RFC7231], Section 4). 198 3.2. formats 200 o Hint Name: formats 202 o Description: Hints the representation type(s) that the target 203 resource can produce and consume, using the GET and PUT (if 204 allowed) methods respectively. 206 o Content Model: object 208 o Specification: [this document] 210 Content MUST be an object, whose keys are media types ([RFC7231], 211 Section 3.1.1.1), and values are objects. 213 The object MAY have a "links" member, whose value is an object 214 representing links (in the sense of [RFC8288]) whose context is any 215 document that uses that format. Generally, this will be schema or 216 profile ([RFC6906]) information. The "links" member has the same 217 format as the "links" hint. 219 Furthermore, the object MAY have a "deprecated" member, whose value 220 is either true or false, indicating whether support for the format 221 might be removed in the near future. 223 All other members of the object are under control of the 224 corresponding media type's definition. 226 3.3. links 228 o Hint Name: links 230 o Description: Hints at links whose context is the target resource. 232 o Content Model: object 234 o Specification: [this document] 236 The "links" hint contains links (in the sense of [RFC8288]) whose 237 context is the hinted target resource, which are stable for the 238 lifetime of the hint. 240 Content MUST be an object, whose member names are link relations 241 ([RFC8288]) and values are objects that MUST have an "href" member 242 whose value is a URI-reference ([RFC3986], using the original link as 243 the base for resolution) for the link hint's target resource, and MAY 244 itself contain link hints, serialised as the value for a "hints" 245 member. 247 For example: 249 "links": { 250 "edit-form": { 251 "href": "./edit", 252 "hints": { 253 formats: { 254 "application/json": {} 255 } 256 } 257 } 258 } 260 3.4. accept-post 262 o Hint Name: accept-post 264 o Description: Hints the POST request format(s) that the target 265 resource can consume. 267 o Content Model: object 269 o Specification: [this document] 271 Content MUST be an object, with the same constraints as for 272 "formats". 274 When this hint is present, "POST" SHOULD be listed in the "allow" 275 hint. 277 3.5. accept-patch 279 o Hint Name: accept-patch 281 o Description: Hints the PATCH [RFC5789] request format(s) that the 282 target resource can consume; equivalent to the Accept-Patch HTTP 283 response header. 285 o Content Model: array (of strings) 287 o Specification: [this document] 289 Content MUST be an array of strings, containing media types 290 ([RFC7231], Section 3.1.1.1). 292 When this hint is present, "PATCH" SHOULD be listed in the "allow" 293 hint. 295 3.6. accept-ranges 297 o Hint Name: accept-ranges 299 o Description: Hints the range-specifier(s) available for the target 300 resource; equivalent to the Accept-Ranges HTTP response header 301 [RFC7233]. 303 o Content Model: array (of strings) 305 o Specification: [this document] 307 Content MUST be an array of strings, containing HTTP range-specifiers 308 ([RFC7233], Section 3.1). 310 3.7. accept-prefer 312 o Hint Name: accept-prefer 314 o Description: Hints the preference(s) [RFC7240] that the target 315 resource understands (and might act upon) in requests. 317 o Content Model: array (of strings) 319 o Specification: [this document] 321 Content MUST be an array of strings, contain preferences ([RFC7240], 322 Section 2). Note that, by its nature, a preference can be ignored by 323 the server. 325 3.8. precondition-req 327 o Hint Name: precondition-req 329 o Description: Hints that the target resource requires state- 330 changing requests (e.g., PUT, PATCH) to include a precondition, as 331 per [RFC7232], to avoid conflicts due to concurrent updates. 333 o Content Model: array (of strings) 335 o Specification: [this document] 337 Content MUST be an array of strings, with possible values "etag" and 338 "last-modified" indicating type of precondition expected. 340 See also the 428 Precondition Required status code ([RFC6585]). 342 3.9. auth-schemes 344 o Hint Name: auth-schemes 346 o Description: Hints that the target resource requires 347 authentication using the HTTP Authentication Framework [RFC7235]. 349 o Content Model: array (of objects) 351 o Specification: [this document] 353 Content MUST be an array of objects, each with a "scheme" member 354 containing a string that corresponds to a HTTP authentication scheme 355 ([RFC7235]), and optionally a "realms" member containing an array of 356 zero to many strings that identify protection spaces that the 357 resource is a member of. 359 For example: 361 { 362 "auth-req": [ 363 { 364 "scheme": "Basic", 365 "realms": ["private"] 366 } 367 ] 368 } 370 3.10. status 372 o Hint Name: status 374 o Description: Hints the status of the target resource. 376 o Content Model: string 378 o Specification: [this document] 380 Content MUST be a string; possible values are: 382 o "deprecated" - indicates that use of the resource is not 383 recommended, but it is still available. 385 o "gone" - indicates that the resource is no longer available; i.e., 386 it will return a 410 Gone HTTP status code if accessed. 388 4. Security Considerations 390 Clients need to exercise care when using hints. For example, a naive 391 client might send credentials to a server that uses the auth-req 392 hint, without checking to see if those credentials are appropriate 393 for that server. 395 5. IANA Considerations 397 5.1. HTTP Link Hint Registry 399 This specification defines the HTTP Link Hint Registry. See 400 Section 2 for a general description of the function of link hints. 402 Link hints are generic; that is, they are potentially applicable to 403 any HTTP resource, not specific to one application of HTTP, nor to 404 one particular format. Generally, they ought to be information that 405 would otherwise be discoverable by interacting with the resource. 407 Hint names MUST be composed of the lowercase letters (a-z), digits 408 (0-9), underscores ("_") and hyphens ("-"), and MUST begin with a 409 lowercase letter. 411 Hint content MUST be described in terms of JSON values ([RFC8259], 412 Section 3). 414 Hint semantics SHOULD be described in terms of the framework defined 415 in [RFC8288]. 417 New hints are registered using the Expert Review process described in 418 [RFC8126] to enforce the criteria above. Requests for registration 419 of new resource hints are to use the following template: 421 o Hint Name: [hint name] 423 o Description: [a short description of the hint's semantics] 425 o Content Model: [valid JSON value types; see RFC627 Section 2.1] 427 o Specification: [reference to specification document] 429 Initial registrations are enumerated in Section 3. The "rel", "rev", 430 "hreflang", "media", "title", and "type" hint names are reserved, so 431 as to avoid potential clashes with link serialisations. 433 6. References 435 6.1. Normative References 437 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 438 Requirement Levels", BCP 14, RFC 2119, 439 DOI 10.17487/RFC2119, March 1997, 440 . 442 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 443 Resource Identifier (URI): Generic Syntax", STD 66, 444 RFC 3986, DOI 10.17487/RFC3986, January 2005, 445 . 447 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 448 RFC 5789, DOI 10.17487/RFC5789, March 2010, 449 . 451 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 452 Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, 453 . 455 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 456 Protocol (HTTP/1.1): Message Syntax and Routing", 457 RFC 7230, DOI 10.17487/RFC7230, June 2014, 458 . 460 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 461 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 462 DOI 10.17487/RFC7231, June 2014, 463 . 465 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 466 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, 467 DOI 10.17487/RFC7232, June 2014, 468 . 470 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 471 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 472 RFC 7233, DOI 10.17487/RFC7233, June 2014, 473 . 475 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 476 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 477 RFC 7234, DOI 10.17487/RFC7234, June 2014, 478 . 480 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 481 Protocol (HTTP/1.1): Authentication", RFC 7235, 482 DOI 10.17487/RFC7235, June 2014, 483 . 485 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, 486 DOI 10.17487/RFC7240, June 2014, 487 . 489 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 490 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 491 May 2017, . 493 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 494 Interchange Format", STD 90, RFC 8259, 495 DOI 10.17487/RFC8259, December 2017, 496 . 498 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 499 DOI 10.17487/RFC8288, October 2017, 500 . 502 6.2. Informative References 504 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, 505 DOI 10.17487/RFC6906, March 2013, 506 . 508 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 509 Writing an IANA Considerations Section in RFCs", BCP 26, 510 RFC 8126, DOI 10.17487/RFC8126, June 2017, 511 . 513 6.3. URIs 515 [1] https://github.com/mnot/I-D/labels/link-hint 517 [2] https://mnot.github.io/I-D/link-hint/ 519 [3] https://github.com/mnot/I-D/commits/gh-pages/link-hint 521 [4] https://datatracker.ietf.org/doc/draft-nottingham-link-hint/ 523 Appendix A. Representing Link Hints in Link Headers 525 A link hint can be represented in a Link header ([RFC8288], 526 Section 3) as a link-extension. 528 When doing so, the JSON of the hint's content SHOULD be normalised to 529 reduce extraneous spaces (%x20), and MUST NOT contain horizontal tabs 530 (%x09), line feeds (%x0A) or carriage returns (%x0D). When they are 531 part of a string value, these characters MUST be escaped as described 532 in [RFC8259] Section 7; otherwise, they MUST be discarded. 534 Furthermore, if the content is an array or an object, the surrounding 535 delimiters MUST be removed before serialisation. In other words, the 536 outermost object or array is represented without the braces ("{}") or 537 brackets ("[]") respectively, but this does not apply to inner 538 objects or arrays. 540 For example, the two JSON values below are those of the fictitious 541 "example" and "example1" hints, respectively: 543 "The Example Value" 544 1.2 546 In a Link header, they would be serialised as: 548 Link: ; rel="sample"; example="The Example Value"; 549 example1=1.2 551 A more complex, single value for "example": 553 [ 554 "foo", 555 -1.23, 556 true, 557 ["charlie", "bennet"], 558 {"cat": "thor"}, 559 false 560 ] 561 would be serialised as: 563 Link: ; rel="sample"; example="\"foo\", -1.23, true, 564 [\"charlie\", \"bennet\"], {"cat": \"thor\"}, false" 566 Appendix B. Acknowledgements 568 Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Graham Klyne, 569 Leif Hedstrom, Jeni Tennison, Erik Wilde and Jorge Williams for their 570 suggestions and feedback. 572 Author's Address 574 Mark Nottingham 576 Email: mnot@mnot.net 577 URI: https://www.mnot.net/