idnits 2.17.1 draft-nottingham-link-hint-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 (June 10, 2013) is 3972 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-22 ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-22 Summary: 3 errors (**), 0 flaws (~~), 6 warnings (==), 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 10, 2013 4 Intended status: Informational 5 Expires: December 12, 2013 7 HTTP Link Hints 8 draft-nottingham-link-hint-00 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 This draft should be discussed on the apps-discuss mailing list; see 19 [apps-discuss]. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on December 12, 2013. 38 Copyright Notice 40 Copyright (c) 2013 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 57 2. HTTP Link Hints . . . . . . . . . . . . . . . . . . . . . . . 4 58 3. Pre-Defined HTTP Link Hints . . . . . . . . . . . . . . . . . 4 59 3.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3.2. formats . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 3.3. links . . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3.4. accept-post . . . . . . . . . . . . . . . . . . . . . . . 6 63 3.5. accept-patch . . . . . . . . . . . . . . . . . . . . . . . 6 64 3.6. accept-ranges . . . . . . . . . . . . . . . . . . . . . . 7 65 3.7. accept-prefer . . . . . . . . . . . . . . . . . . . . . . 7 66 3.8. precondition-req . . . . . . . . . . . . . . . . . . . . . 7 67 3.9. auth-schemes . . . . . . . . . . . . . . . . . . . . . . . 7 68 3.10. status . . . . . . . . . . . . . . . . . . . . . . . . . . 8 69 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 71 5.1. HTTP Link Hint Registry . . . . . . . . . . . . . . . . . 8 72 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 73 6.1. Normative References . . . . . . . . . . . . . . . . . . . 9 74 6.2. Informative References . . . . . . . . . . . . . . . . . . 10 75 Appendix A. Representing Link Hints in Link Headers . . . . . . . 11 76 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 12 77 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . . 12 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 80 1. Introduction 82 Clients can discover a variety of information about a HTTP 83 [I-D.ietf-httpbis-p1-messaging] resource by interacting with it. For 84 example, the methods supported can be learned through the Allow 85 response header field, whereas the need for authentication is 86 conveyed with a 401 Authentication Required status code. 88 In some situations, it can be beneficial to know this information 89 before interacting with the resource; not only can it save time 90 (through reduced round trips), but it can also affect the choices 91 given to the code or user driving the interaction. 93 For example, a user interface that presents the data from an HTTP- 94 based API might need to know which resources the user has write 95 access to, so that it can present the appropriate interface. 97 This specification defines a vocabulary of "HTTP link hints" that 98 allow such metadata about HTTP resources to be attached to Web links 99 [RFC5988], thereby making it available before the link is followed. 100 It also establishes a registry for future hints. 102 It does not recommend a single serialisation format for link hints; 103 rather, it is expected that this will be done by individual link 104 serialisations that use hints (whether they be in a representation 105 body, message headers or elsewhere). However, Appendix A does 106 recommend how to include link hints in the existing Link HTTP header 107 field. 109 Hints are just that - they are not a "contract", and are to only be 110 taken as advisory. The runtime behaviour of the resource always 111 overrides hinted information. 113 For example, a client might receive a hint that the PUT method is 114 allowed on all "widget" resources. This means that generally, the 115 client can PUT to them, but a specific resource might reject a PUT 116 based upon access control or other considerations. 118 More fine-grained information might be gathered by interacting with 119 the resource (e.g., via a GET), or by another resource "containing" 120 it (such as a "widgets" collection) or describing it (e.g., one 121 linked to it with a "describedby" link relation). 123 1.1. Notational Conventions 125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 126 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 127 document are to be interpreted as described in [RFC2119]. 129 2. HTTP Link Hints 131 A HTTP link hint is a (key, value) tuple that describes the target 132 resource of a Web link [RFC5988], or the link itself. The value's 133 canonical form is a JSON [RFC4627] data structure, whose form is 134 defined by the hint's definition. 136 Typically, they are serialised in links as target attributes. 138 In JSON-based formats, this can be achieved by simply serialising 139 link hints as an object; for example: 141 { 142 "_links": { 143 "self": { 144 "href": "/orders/523", 145 "hints": { 146 "allow": ["GET", "POST"], 147 "accept-post": { 148 "application/example+json": 149 {} 150 } 151 } 152 } 153 } 154 } 156 In other link formats, this requires a mapping from the canonical 157 JSON data model. One such mapping for the Link HTTP header is 158 described in Appendix A. 160 The information in a link hint SHOULD NOT be considered valid for 161 longer than the freshness lifetime ([I-D.ietf-httpbis-p6-cache]) of 162 the representation that the link occurred within, and in some cases, 163 it might be valid for a considerably shorter period. 165 Likewise, the information in a link hint is specific to the link it 166 is attached to. This means that if a representation is specific to a 167 particular user, the hints on links in that representation are also 168 specific to that user. 170 3. Pre-Defined HTTP Link Hints 172 3.1. allow 173 o Hint Name: allow 174 o Description: Hints the HTTP methods that can be used to interact 175 with the target resource; equivalent to the Allow HTTP response 176 header. 177 o Content Model: array (of strings) 178 o Specification: [this document] 180 Content MUST be an array of strings, containing HTTP methods. 182 3.2. formats 184 o Hint Name: formats 185 o Description: Hints the representation type(s) that the target 186 resource can produce and consume, using the GET and PUT (if 187 allowed) methods respectively. 188 o Content Model: object 189 o Specification: [this document] 191 Content MUST be an object, whose keys are media types, and values are 192 objects. 194 The object MAY have a "links" member, whose value is an object 195 representing links (in the sense of [RFC5988]) whose context is any 196 document that uses that format. Generally, this will be schema or 197 profile ([RFC6906]) information. The "links" member has the same 198 format as the "links" hint. 200 Furthermore, the object MAY have a "deprecated" member, whose value 201 is either true or false, indicating whether support for the format 202 might be removed in the near future. 204 All other members of the object are under control of the 205 corresponding media type's definition. 207 3.3. links 209 o Hint Name: links 210 o Description: Hints at links whose context is the target resource. 211 o Content Model: object 212 o Specification: [this document] 214 The "links" hint contains links (in the sense of [RFC5988]) whose 215 context is the hinted target resource, which are stable for the 216 lifetime of the hint. 218 Content MUST be an object, whose member names are link relations 219 ([RFC5988]) and values are objects that MUST have an "href" member 220 whose value is a URI-reference ([RFC3986], using the original link as 221 the base for resolution) for the link hint's target resource, and MAY 222 itself contain link hints, serialised as the value for a "hints" 223 member. 225 For example: 227 "links": { 228 "edit-form": { 229 "href": "./edit", 230 "hints": { 231 formats: { 232 "application/json": {} 233 } 234 } 235 } 236 } 238 3.4. accept-post 240 o Hint Name: accept-post 241 o Description: Hints the POST request format(s) that the target 242 resource can consume. 243 o Content Model: object 244 o Specification: [this document] 246 Content MUST be an object, with the same constraints as for 247 "formats". 249 When this hint is present, "POST" SHOULD be listed in the "allow" 250 hint. 252 3.5. accept-patch 254 o Hint Name: accept-patch 255 o Description: Hints the PATCH [RFC5789] request format(s) that the 256 target resource can consume; equivalent to the Accept-Patch HTTP 257 response header. 258 o Content Model: array (of strings) 259 o Specification: [this document] 261 Content MUST be an array of strings, containing media types. Note 262 that there is no opportunity to communicate format-specific hints for 263 PATCH formats. 265 When this hint is present, "PATCH" SHOULD be listed in the "allow" 266 hint. 268 3.6. accept-ranges 270 o Hint Name: accept-ranges 271 o Description: Hints the range-specifier(s) available for the target 272 resource; equivalent to the Accept-Ranges HTTP response header 273 [I-D.ietf-httpbis-p5-range]. 274 o Content Model: array (of strings) 275 o Specification: [this document] 277 Content MUST be an array of strings, containing HTTP range- 278 specifiers. 280 3.7. accept-prefer 282 o Hint Name: accept-prefer 283 o Description: Hints the preference(s) [I-D.snell-http-prefer] that 284 the target resource understands (and might act upon) in requests. 285 o Content Model: array (of strings) 286 o Specification: [this document] 288 Content MUST be an array of strings, contain preferences. Note that, 289 by its nature, a preference can be ignored by the server. 291 3.8. precondition-req 293 o Hint Name: precondition-req 294 o Description: Hints that the target resource requires state- 295 changing requests (e.g., PUT, PATCH) to include a precondition, as 296 per [I-D.ietf-httpbis-p4-conditional], to avoid conflicts due to 297 concurrent updates. 298 o Content Model: array (of strings) 299 o Specification: [this document] 301 Content MUST be an array of strings, with possible values "etag" and 302 "last-modified" indicating type of precondition expected. 304 See also the 428 Precondition Required status code ([RFC6585]). 306 3.9. auth-schemes 308 o Hint Name: auth-schemes 309 o Description: Hints that the target resource requires 310 authentication using the HTTP Authentication Framework 311 [I-D.ietf-httpbis-p7-auth]. 312 o Content Model: array (of objects) 313 o Specification: [this document] 315 Content MUST be an array of objects, each with a "scheme" member 316 containing a string that corresponds to a HTTP authentication scheme, 317 and optionally a "realms" member containing an array of zero to many 318 strings that identify protection spaces that the resource is a member 319 of. 321 For example: 323 { 324 "auth-req": [ 325 { 326 "scheme": "Basic", 327 "realms": ["private"] 328 } 329 ] 330 } 332 3.10. status 334 o Hint Name: status 335 o Description: Hints the status of the target resource. 336 o Content Model: string 337 o Specification: [this document] 339 Content MUST be a string; possible values are: 341 o "deprecated" - indicates that use of the resource is not 342 recommended, but it is still available. 343 o "gone" - indicates that the resource is no longer available; i.e., 344 it will return a 410 Gone HTTP status code if accessed. 346 4. Security Considerations 348 Clients need to exercise care when using hints. For example, a naive 349 client might send credentials to a server that uses the auth-req 350 hint, without checking to see if those credentials are appropriate 351 for that server. 353 5. IANA Considerations 355 5.1. HTTP Link Hint Registry 357 This specification defines the HTTP Link Hint Registry. See 358 Section 2 for a general description of the function of link hints. 360 Link hints are generic; that is, they are potentially applicable to 361 any HTTP resource, not specific to one application of HTTP, nor to 362 one particular format. Generally, they ought to be information that 363 would otherwise be discoverable by interacting with the resource. 365 Hint names MUST be composed of the lowercase letters (a-z), digits 366 (0-9), underscores ("_") and hyphens ("-"), and MUST begin with a 367 lowercase letter. 369 Hint content MUST be described in terms of JSON values ([RFC4627], 370 Section 2.1). 372 Hint semantics SHOULD be described in terms of the framework defined 373 in [RFC5988]. 375 New hints are registered using the Expert Review process described in 376 [RFC5226] to enforce the criteria above. Requests for registration 377 of new resource hints are to use the following template: 379 o Hint Name: [hint name] 380 o Description: [a short description of the hint's semantics] 381 o Content Model: [valid JSON value types; see RFC627 Section 2.1] 382 o Specification: [reference to specification document] 384 Initial registrations are enumerated in Section 3. The "rel", "rev", 385 "hreflang", "media", "title", and "type" hint names are reserved, so 386 as to avoid potential clashes with link serialisations. 388 6. References 390 6.1. Normative References 392 [I-D.ietf-httpbis-p1-messaging] 393 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 394 (HTTP/1.1): Message Syntax and Routing", 395 draft-ietf-httpbis-p1-messaging-22 (work in progress), 396 February 2013. 398 [I-D.ietf-httpbis-p6-cache] 399 Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 400 Transfer Protocol (HTTP/1.1): Caching", 401 draft-ietf-httpbis-p6-cache-22 (work in progress), 402 February 2013. 404 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 405 Requirement Levels", BCP 14, RFC 2119, March 1997. 407 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 408 Resource Identifier (URI): Generic Syntax", STD 66, 409 RFC 3986, January 2005. 411 [RFC4627] Crockford, D., "The application/json Media Type for 412 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 414 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 415 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 416 May 2008. 418 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 420 6.2. Informative References 422 [I-D.ietf-httpbis-p4-conditional] 423 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 424 (HTTP/1.1): Conditional Requests", 425 draft-ietf-httpbis-p4-conditional-22 (work in progress), 426 February 2013. 428 [I-D.ietf-httpbis-p5-range] 429 Fielding, R., Lafon, Y., and J. Reschke, "Hypertext 430 Transfer Protocol (HTTP/1.1): Range Requests", 431 draft-ietf-httpbis-p5-range-22 (work in progress), 432 February 2013. 434 [I-D.ietf-httpbis-p7-auth] 435 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 436 (HTTP/1.1): Authentication", draft-ietf-httpbis-p7-auth-22 437 (work in progress), February 2013. 439 [I-D.snell-http-prefer] 440 Snell, J., "Prefer Header for HTTP", 441 draft-snell-http-prefer-18 (work in progress), 442 January 2013. 444 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 445 RFC 5789, March 2010. 447 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 448 Codes", RFC 6585, April 2012. 450 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, 451 March 2013. 453 [apps-discuss] 454 IETF, "IETF Apps-Discuss Mailing List", n.d., 455 . 457 Appendix A. Representing Link Hints in Link Headers 459 A link hint can be represented in a Link header ([RFC5988], Section 460 5) as a link-extension. 462 When doing so, the JSON of the hint's content SHOULD be normalised to 463 reduce extraneous spaces (%x20), and MUST NOT contain horizontal tabs 464 (%x09), line feeds (%x0A) or carriage returns (%x0D). When they are 465 part of a string value, these characters MUST be escaped as described 466 in [RFC4627] Section 2.5; otherwise, they MUST be discarded. 468 Furthermore, if the content is an array or an object, the surrounding 469 delimiters MUST be removed before serialisation. In other words, the 470 outermost object or array is represented without the braces ("{}") or 471 brackets ("[]") respectively, but this does not apply to inner 472 objects or arrays. 474 For example, the two JSON values below are those of the fictitious 475 "example" and "exmaple1" hints, respectively: 477 "The Example Value" 478 1.2 480 In a Link header, they would be serialised as: 482 Link: ; rel="sample"; example="The Example Value"; 483 example1=1.2 485 A more complex, single value for "example": 487 [ 488 "foo", 489 -1.23, 490 true, 491 ["charlie", "bennet"], 492 {"cat": "thor"}, 493 false 494 ] 496 would be serialised as: 498 Link: ; rel="sample"; example="\"foo\", -1.23, true, 499 [\"charlie\", \"bennet\"], {"cat": \"thor\"}, false" 501 Appendix B. Acknowledgements 503 Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Graham Klyne, 504 Leif Hedstrom, Jeni Tennison, Erik Wilde and Jorge Williams for their 505 suggestions and feedback. 507 Appendix C. Open Issues 509 The following is a list of placeholders for open issues. 511 o Resource Hints 512 * indicate a POST to 201 Created pattern 513 * indicate an "action" POST 514 * outbound links 515 * forms? 516 o Representation Hints 517 * format profiles 518 * schema? 519 * deprecation 521 Author's Address 523 Mark Nottingham 525 Email: mnot@mnot.net 526 URI: http://www.mnot.net/