idnits 2.17.1 draft-dunglas-vulcain-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: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The abstract seems to contain references ([RFC7540], [RFC8297]), 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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (3 April 2020) is 1484 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group K. Dunglas 3 Internet-Draft Les-Tilleuls.coop 4 Intended status: Informational 3 April 2020 5 Expires: 5 October 2020 7 The Vulcain Protocol 8 draft-dunglas-vulcain-00 10 Abstract 12 This specification defines new HTTP headers (and query parameters) 13 allowing a client to inform the server of the exact data it needs: 15 * "Preload" informs the server that relations of the main requested 16 resource will be necessary. The server can then reduce the number 17 of round-trips by sending the related resources ahead of time 18 using HTTP/2 [RFC7540] Server Push. When using Server Push isn't 19 possible (resources served by a different authority, server not 20 supporting HTTP/2...), the server can hint the client to fetch 21 those resources as early as possible by using the "preload" link 22 relation [W3C.CR-preload-20171026] and the "103" status code 23 [RFC8297]. 25 * "Fields" informs the server of the list of fields of the retrieved 26 resources that will be used. In order to improve performance and 27 reduce bandwidth usage, the server can omit the fields not 28 requested. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on 5 October 2020. 47 Copyright Notice 49 Copyright (c) 2020 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 54 license-info) in effect on the date of publication of this document. 55 Please review these documents carefully, as they describe your rights 56 and restrictions with respect to this document. Code Components 57 extracted from this document must include Simplified BSD License text 58 as described in Section 4.e of the Trust Legal Provisions and are 59 provided without warranty as described in the Simplified BSD License. 61 Table of Contents 63 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 64 2. Preload Header . . . . . . . . . . . . . . . . . . . . . . . 2 65 2.1. Using Preload Link Relations . . . . . . . . . . . . . . 4 66 3. Fields Header . . . . . . . . . . . . . . . . . . . . . . . . 4 67 4. Selectors . . . . . . . . . . . . . . . . . . . . . . . . . . 6 68 4.1. Extended JSON Pointer . . . . . . . . . . . . . . . . . . 7 69 5. Query Parameters . . . . . . . . . . . . . . . . . . . . . . 8 70 6. Computing Links Server-Side . . . . . . . . . . . . . . . . . 8 71 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 72 8. IANA considerations . . . . . . . . . . . . . . . . . . . . . 9 73 9. Normative References . . . . . . . . . . . . . . . . . . . . 9 74 10. Informative References . . . . . . . . . . . . . . . . . . . 10 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 77 1. Terminology 79 The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, 80 *SHOULD NOT*, RECOMMENDED, MAY, and OPTIONAL, when they appear in 81 this document, are to be interpreted as described in [RFC2119]. 83 2. Preload Header 85 Many formats including HTML [W3C.REC-html52-20171214], JSON-LD 86 [W3C.REC-json-ld-20140116], Atom [RFC4287], XML 87 [W3C.REC-xml-20081126], HAL (https://tools.ietf.org/html/draft-kelly- 88 json-hal-08) and JSON:API (https://jsonapi.org/) allow the use of Web 89 Linking [RFC5988] to represent references between resources. 91 The "Preload" HTTP header allows the client to ask the server to 92 transmit resources linked to the main resource it will need as soon 93 as possible. To do so, the "Preload" header "MUST" contain a 94 selector [#selectors] referencing links to resources that "SHOULD" be 95 preloaded. 97 The server "MUST" recursively follow links referenced by the 98 selector. When a selector traverses several resources, all the 99 traversed resources "SHOULD" be sent to the client. If several links 100 referencing the same resource are selected, this resource "MUST" be 101 sent at most once. 103 The server "MAY" limit the number resources that it sends in response 104 to one request. 106 Multiple selectors can be sent by passing multiple "Preload" HTTP 107 headers. 109 Considering the following resources: 111 "/books" 113 { 114 "member": [ 115 "/books/1", 116 "/books/2" 117 ] 118 } 120 "/books/1" 122 { 123 "title": "1984", 124 "author": "/authors/1" 125 } 127 "/books/2" 129 { 130 "title": "Homage to Catalonia", 131 "author": "/authors/1" 132 } 134 "/authors/1" 136 { 137 "givenName": "George", 138 "familyName": "Orwell" 139 } 140 The "Preload" HTTP header can be used to ask the server to 141 immediately push resources related to the requested one: 143 GET /books/ HTTP/2 144 Preload: /member/*/author 146 In addition to "/books", the server "SHOULD" use HTTP/2 Server Push 147 to push the "/books/1", "/books/2" and "/authors/1" resources. While 148 it is referenced twice, "/authors/1" "MUST" be pushed only once. 150 Server Push requests generated by the server for related resources 151 "MUST" include the remaining selector in a "Preload" HTTP header. 152 When requesting a pushed relation, the client "MUST" compute the 153 remaining selector and pass it in the "Preload" header. 155 Example: 157 Explicit Request: 159 GET /books/ HTTP/2 160 Preload: /member/*/author 162 Request to a relation generated by the server (for the push) and the 163 client: 165 GET /books/1 HTTP/2 166 Preload: /author 168 2.1. Using Preload Link Relations 170 If it's not possible or beneficial to use HTTP/2 Server Push 171 (reference to a resource not served by the same authority, client or 172 server not supporting HTTP/2, client having disabled Server Push...), 173 "preload" link relations [W3C.CR-preload-20171026] "SHOULD" be used 174 as a fallback. 176 The server "MUST NOT" add "preload" link relations if the related 177 resources are pushed using HTTP/2 Server Push. 179 3. Fields Header 181 The "Fields" HTTP header allows the client to ask the server to 182 return only the specified fields of the requested resource, and of 183 the preloaded related resources. 185 The "Fields" HTTP header "MUST" contain a selector (see #Selector). 186 The server "SHOULD" return only the fields matching this selector. 188 Multiple "Fields" HTTP headers can be passed. All fields matching at 189 least one of these headers "MUST" be returned. Other fields of the 190 resource "MAY" be omitted. 192 Considering the following resources: 194 "/books/1" 196 { 197 "title": "1984", 198 "genre": "novel", 199 "author": "/authors/1" 200 } 202 "/authors/1" 204 { 205 "givenName": "George", 206 "familyName": "Orwell" 207 } 209 And the following HTTP request: 211 GET /books/1 HTTP/2 212 Preload: /author 213 Fields: /author/familyName 214 Fields: /genre 216 The server must return a response containing the following JSON 217 document: 219 { 220 "genre": "novel", 221 "author": "/authors/1" 222 } 224 And push the following filtered "/authors/1" resource: 226 { 227 "familyName": "Orwell" 228 } 230 Server Push requests generated by the server for related resources 231 "MUST" include the remaining selector in a "Fields" HTTP header. 232 When requesting a pushed relation, the client "MUST" compute the 233 remaining selector and pass it in the "Fields" header. 235 Example: 237 Explicit Request: 239 GET /books/ HTTP/2 240 Fields: /member/*/author 242 Request to a relation generated by the server (for the push) and the 243 client: 245 GET /books/1 HTTP/2 246 Fields: /author 248 4. Selectors 250 Selectors used as value of the "Preload" and "Fields" HTTP headers 251 depend on the "Content-Type" of the requested resource. This 252 specification defines default selector formats for common content- 253 types, and a mechanism to use other selector formats. 255 The client "SHOULD" use the "Accept" HTTP header to request the 256 resource in a format compatible with selectors used in "Preload" and 257 "Fields" HTTP headers. 259 The client can use the "Prefer" HTTP header [RFC7240] with the 260 "selector" preference to ask the server to use a specific selector 261 format: 263 GET /books/1 HTTP/2 264 Accept: text/xml 265 Prefer: selector=css 266 Fields: brand > name 268 If no explicit preferences have been passed, the server "MUST" assume 269 that the selector format is the default corresponding to the format 270 of the resource. 272 The following table defines the default selector format for common 273 formats: 275 +--------+-----------------------------------+----------------+ 276 | Format | Selector format | Identifier | 277 +========+===================================+================+ 278 | JSON | Extended JSON Pointer Section 4.1 | "json-pointer" | 279 +--------+-----------------------------------+----------------+ 280 | XML | XPath [W3C.REC-xpath-19991116] | "xpath" | 281 +--------+-----------------------------------+----------------+ 282 | HTML | CSS selectors | "css" | 283 | | [W3C.REC-selectors-3-20181106] | | 284 +--------+-----------------------------------+----------------+ 286 Table 1 288 The client and the server can negotiate the use of other selector 289 formats using the "Prefer" HTTP header. 291 4.1. Extended JSON Pointer 293 For JSON documents, the default selector format is JSON Pointer 294 [RFC6901]. However, JSON Pointer doesn't provide a mechanism to 295 select entire collections. 297 This specification defines an extension to the JSON Pointer format 298 allowing to select every element of a collection, the "*" character. 300 Considering the following JSON document: 302 { 303 "books": [ 304 { 305 "title": "1984", 306 "author": "George Orwell" 307 }, 308 { 309 "title": "The Handmaid's Tale", 310 "author": "Margaret Atwood" 311 } 312 ] 313 } 315 The "/books/*/author" JSON Pointer selects the "author" field of 316 every objects in the "books" array. 318 The "*" character is escaped by encoding it as the "~2" character 319 sequence. 321 By design, this selector is simple and limited. Simple selectors 322 make it easier to limit the complexity of requests executed by the 323 server. 325 5. Query Parameters 327 Another option available to clients is to utilize Request URI query- 328 string parameters to pass preload and fields selectors. The 329 "preload" and "query" parameters "MAY" be used to pass selectors 330 corresponding respectively to the "Preload" and "Fields" HTTP 331 headers. To pass multiple selectors, parameters can be passed 332 multiple times. 334 Example: "/books/1?fields=/title&fields=/author&preload=/author" 336 When using query parameters, the server "MUST" pass the remaining 337 part of the selector as parameter of the generated link. 339 Example: 341 GET /books/?preload=/member/*/author HTTP/2 343 { 344 "member": { 345 "/books/1?preload=/author", 346 "/books/1?preload=/author" 347 } 348 } 350 As altering the URI can have undesirable effects, using HTTP headers 351 "SHOULD" be preferred. Support for query parameters is "OPTIONAL". 352 A server supporting query parameters "MUST" also support the 353 corresponding HTTP headers. 355 6. Computing Links Server-Side 357 While using hypermedia capabilities of the HTTP protocol through Web 358 Linking "SHOULD" always be preferred, sometimes links between 359 resources are known by the server but are not provided in the HTTP 360 response. 362 In such cases, the server can compute the link server-side in order 363 to push the related resource. Such server-side computed links "MAY" 364 be documented, for instance by providing an OpenAPI specification 365 (https://www.openapis.org/) containing Link objects 366 (http://spec.openapis.org/oas/v3.0.2#link-object). 368 Considering the following resources and assuming that the server 369 knows that the "author" field references the resources 370 "/authors/{id}" resource: 372 "/books/1" 374 { 375 "title": "1984", 376 "author": 1 377 } 379 "/authors/1" 381 { 382 "givenName": "George", 383 "familyName": "Orwell" 384 } 386 In response to this request , both "/books/1" and "/authors/1" should 387 be pushed: 389 GET /books/1 HTTP/2 390 Preload: /author 392 7. Security Considerations 394 Using the "Preload" header can lead to a large number of resources to 395 be generated and pushed. The server "SHOULD" limit the maximum 396 number of resources to push. The depth of the selector "SHOULD" also 397 be limited by the server. 399 8. IANA considerations 401 The "Preload"and "Fields" header fields will be added to the 402 "Permanent Message Header Field Names" registry defined in [RFC3864]. 404 A selector registry could also be added. 406 9. Normative References 408 [RFC8297] Oku, K., "An HTTP Status Code for Indicating Hints", 409 RFC 8297, DOI 10.17487/RFC8297, December 2017, 410 . 412 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 413 DOI 10.17487/RFC5988, October 2010, 414 . 416 [W3C.REC-selectors-3-20181106] 417 A‡elik, T., Etemad, E., Glazman, D., Hickson, I., Linss, 418 P., and J. Williams, "Selectors Level 3", World Wide Web 419 Consortium Recommendation REC-selectors-3-20181106, 6 420 November 2018, 421 . 423 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 424 Procedures for Message Header Fields", BCP 90, RFC 3864, 425 DOI 10.17487/RFC3864, September 2004, 426 . 428 [W3C.CR-preload-20171026] 429 Grigorik, I. and Y. Weiss, "Preload", World Wide Web 430 Consortium CR CR-preload-20171026, 26 October 2017, 431 . 433 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 434 Requirement Levels", BCP 14, RFC 2119, 435 DOI 10.17487/RFC2119, March 1997, 436 . 438 [W3C.REC-xpath-19991116] 439 Clark, J. and S. DeRose, "XML Path Language (XPath) 440 Version 1.0", World Wide Web Consortium Recommendation 441 REC-xpath-19991116, 16 November 1999, 442 . 444 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 445 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 446 DOI 10.17487/RFC7540, May 2015, 447 . 449 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, 450 DOI 10.17487/RFC7240, June 2014, 451 . 453 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 454 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 455 DOI 10.17487/RFC6901, April 2013, 456 . 458 10. Informative References 460 [W3C.REC-html52-20171214] 461 Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and 462 S. Moon, "HTML 5.2", World Wide Web Consortium 463 Recommendation REC-html52-20171214, 14 December 2017, 464 . 466 [W3C.REC-json-ld-20140116] 467 Sporny, M., Kellogg, G., and M. Lanthaler, "JSON-LD 1.0", 468 World Wide Web Consortium Recommendation REC-json-ld- 469 20140116, 16 January 2014, 470 . 472 [W3C.REC-xml-20081126] 473 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 474 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 475 Edition)", World Wide Web Consortium Recommendation REC- 476 xml-20081126, 26 November 2008, 477 . 479 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 480 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 481 December 2005, . 483 Author's Address 485 Kevin Dunglas 486 Les-Tilleuls.coop 487 2 rue Hegel 488 59000 Lille 489 France 491 Email: kevin@les-tilleuls.coop