idnits 2.17.1 draft-pot-prefer-push-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 (May 02, 2019) is 1811 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-header-structure-10 ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) Summary: 1 error (**), 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. Pot 3 Internet-Draft May 02, 2019 4 Intended status: Standards Track 5 Expires: November 3, 2019 7 HTTP-client suggested Push Preference 8 draft-pot-prefer-push-01 10 Abstract 12 "Prefer-Push" is a HTTP header that a client may use to request that 13 a server uses HTTP/2 Push to send related resources as identified by 14 their link relationships. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at https://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on November 3, 2019. 33 Copyright Notice 35 Copyright (c) 2019 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (https://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 1. Introduction 50 HTTP/2 [RFC7540] allows a server to push request and response pairs 51 to HTTP clients. This can save round-trips between server and client 52 and reduces the total time required for a client to retrieve all 53 requested resources. 55 This mechanism is completely controlled by the server, and it is up 56 to implementors of services to anticipate what resources a client 57 might need next. 59 This specification defines a new HTTP header that allows a client to 60 inform a server of resources they will require next based on a link 61 relation type [RFC8288]. 63 2. Rationale 65 Many HTTP-based services provide some mechanism to embed the HTTP 66 response bodies of resources into other HTTP resource. A common 67 example of this is when a resource is structured as a "collection of 68 resources". Examples of this include: 70 o The Atom Syndication Format [RFC4287] that encodes "ATOM:entry" 71 XML elements for each subordinate. 73 o The [HAL] format, which provides an "_embedded" element to 74 embedding bodies of resources in other resources. 76 o The [JSON-API] format, which provides a "included" property to 77 embed resources. 79 Embedding resource responses in other resources has two major 80 peformance advantages: 82 1. It reduces the number of roundtrips. A client can make a single 83 HTTP request and get many responses. 85 2. Generating a related set of resources can often be implemented on 86 a server to be less time consuming than generating each response 87 individually. 89 These mechanisms also pose an issue. To HTTP clients and 90 intermediaries such as proxies and caches resources are opaque. They 91 are not aware of a concept of embedded resources. 93 One example where this might fail is if a client recieves a resource, 94 embedded in another resource, a cache might not be aware of this 95 resource and serve a stale, older version when this resource is 96 requesed directly. 98 To keep the performance advantage of being able to generate a related 99 set of HTTP responses together, HTTP/2 Push could be an alternative 100 to embedding. 102 HTTP/2 Push allows the server to initiate a request and response pair 103 and send them to the client early if the server thinks it will need 104 them. Another advantage of HTTP/2 push over embedding is that it 105 allows resources of mixed mediatypes to be pushed. 107 Servers can however not always anticipate which resources a client 108 might want pushed. To avoid guessing, this specification introduces 109 a "Prefer-Push" header that allows a client to inform a server which 110 resources they will need next. 112 In many REST apis, sub-ordiniate or embedded resources are identified 113 by their link relation. By using the link relation, it will be 114 possible for a client to indicate to a server which links they intent 115 to follow, allowing a server to only push the resources that the 116 client knows it will need. 118 3. The header format 120 This format should the "List" Data Type from the Structured Headers 121 specification [I-D.ietf-httpbis-header-structure]. 123 GET /articles HTTP/1.1 124 Prefer-Push: item, author, "https://example.org/custom-rel" 126 Each item in the list is a link relationship, as described in Web 127 Links [RFC8288]. 129 4. Handling a Prefer-Push request 131 When a server receives the "Prefer-Push" header, it can choose to 132 push the related resources. It's up to the discretion of the 133 implementor to decide which resources to push. A server is also free 134 to ignore push-requests. 136 If a server chooses to act on an item in the "Prefer-Push" list, the 137 Link Relationship should exist at the target resource. This 138 specification does not require that the link relationships get 139 returned as HTTP "Link" headers. The "Link" may be defined as 140 "" HTML element, or as a JSON property. How the link is 141 serialized is dependent on the media type. 143 5. Using with "preload" relationship types 145 [W3C.CR-preload-20171026] defines a "preload" relationship type. 146 This relationship type can be used by an origin to inform a client or 147 intermediate to start fetching a resource, or a proxy to initiate a 148 HTTP/2 push. 150 A distinct difference between "preload" and "Prefer-Push" is that 151 "preload" can be used by origin servers to inform clients and 152 intermediates to fetch and potentially push resources optimistically, 153 but fundamentally "Prefer-Push" is a completely client-driven 154 mechanism. 156 These features can co-exist, but a wide adoption of client-driven 157 suggestions for pushes might eventually make "preload" unnecceary as 158 in most cases clients will have a better knowledge of the resources 159 they need. 161 6. Security considerations 163 The Prefer-Push mechanism can potentially result in a large number of 164 resources being pushed. This can result in a Denial-of-Service 165 attack. 167 A server must set reasonable restrictions around the number of pushed 168 resources. 170 7. IANA considerations 172 This document defines the "Prefer-Push" HTTP request fields and 173 registers them in the Permanent Message Header Fields registry. 175 7.1. Prefer-Push 177 o Header field name: Prefer-Push 179 o Applicable protocol: HTTP 181 o Status: standard 183 o Author/Change controller: IETF 185 o Specification document(s): Section 7.1 of this document 187 o Related information: for Client Hints 189 8. Acknowledgements 191 9. References 193 9.1. Normative References 195 [I-D.ietf-httpbis-header-structure] 196 Nottingham, M. and P. Kamp, "Structured Headers for HTTP", 197 draft-ietf-httpbis-header-structure-10 (work in progress), 198 April 2019. 200 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 201 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 202 DOI 10.17487/RFC7540, May 2015, 203 . 205 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 206 DOI 10.17487/RFC8288, October 2017, 207 . 209 [W3C.CR-preload-20171026] 210 Grigorik, I. and Y. Weiss, "Preload", World Wide Web 211 Consortium CR CR-preload-20171026, October 2017, 212 . 214 9.2. Informative References 216 [HAL] Kelly, M., "JSON Hypertext Application Language", June 217 2012, 218 . 220 [JSON-API] 221 "JSON:API", n.d., . 223 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 224 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 225 December 2005, . 227 Appendix A. Example 229 A server serves a document with a JSON-based media-type. The 230 following example document might represent a list of articles: 232 HTTP/1.1 200 OK 233 Content-Type: application/vnd.example.links+json 235 { 236 "links": [ 237 { "rel": "item", "href": "/article/1" }, 238 { "rel": "item", "href": "/article/2" }, 239 { "rel": "item", "href": "/article/3" }, 240 { "rel": "item", "href": "/article/4" }, 241 { "rel": "item", "href": "/article/5" } 242 ] 243 "total" : 5, 244 } 246 A "Prefer-Push"-enabled client knows it will want to receive the full 247 representations of all articles. When the client receives the list 248 of articles via a "GET" request, it can indicate this preference with 249 the "Prefer-Push" header: 251 GET /article HTTP/1.1 252 Accept: application/vnd.example.links+json 253 Prefer-Push: item 255 Upon recieving this request, server may immediately generate the 256 request and response pairs for every "item" link in the collection 257 and initiate push streams for each. 259 Appendix B. Changelog 261 B.1. Changes since -00 263 o Added an abstract 265 o Updated rationale section significantly. 267 Author's Address 269 Evert Pot 271 Email: me@evertpot.com 272 URI: https://evertpot.com/