idnits 2.17.1 draft-prudhommeaux-http-status-2nn-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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [3], [4], [5], [6], [7], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 30, 2014) is 3588 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 329 -- Looks like a reference, but probably isn't: '2' on line 331 -- Looks like a reference, but probably isn't: '3' on line 333 -- Looks like a reference, but probably isn't: '4' on line 335 -- Looks like a reference, but probably isn't: '5' on line 337 -- Looks like a reference, but probably isn't: '6' on line 339 -- Looks like a reference, but probably isn't: '7' on line 341 -- Looks like a reference, but probably isn't: '8' on line 343 -- Looks like a reference, but probably isn't: '9' on line 345 -- Looks like a reference, but probably isn't: '10' on line 146 -- Looks like a reference, but probably isn't: '11' on line 155 -- Looks like a reference, but probably isn't: '12' on line 257 -- Looks like a reference, but probably isn't: '13' on line 264 -- Looks like a reference, but probably isn't: '14' on line 280 -- Looks like a reference, but probably isn't: '15' on line 289 -- Looks like a reference, but probably isn't: '16' on line 301 -- Looks like a reference, but probably isn't: '17' on line 325 ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Prud'hommeaux 3 Internet-Draft W3C 4 Intended status: Experimental June 30, 2014 5 Expires: January 1, 2015 7 The Hypertext Transfer Protocol (HTTP) Status Code 2NN (Contents of 8 Related) 9 draft-prudhommeaux-http-status-2nn-00 11 Abstract 13 This document specifies the additional HyperText Transfer Protocol 14 (HTTP) Status Code 2NN (Contents of Related). It also specified a 15 Prefer header value "contents-of-related" which clients can use to 16 indicate that they can accept 2NN responses. 18 Editorial Note (To be removed by RFC Editor before publication) 20 Distribution of this document is unlimited. Comments should be sent 21 to the W3C Technical Architecture Group mailing list at www- 22 tag@w3.org [1] (public archive [2]) and the Linked Data Platform 23 mailing list at public-ldp-comments@w3.org [3] (public archive [4]). 24 The latter list may be joined by sending a message with subject 25 "subscribe" to public-ldp-comments-request@w3.org [5]. 27 XML versions, latest edits, and the issues list for this document are 28 available from [6]. 30 Test cases related to redirection in general and the status code 2NN 31 in particular can be found at [7] as a template. 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on January 1, 2015. 50 Copyright Notice 52 Copyright (c) 2014 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 68 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 69 3. 2NN Contents of Related . . . . . . . . . . . . . . . . . . . 3 70 3.1. Caching Semantics . . . . . . . . . . . . . . . . . . . . 6 71 4. contents-of-related Prefer header value . . . . . . . . . . . 6 72 5. Deployment Considerations . . . . . . . . . . . . . . . . . . 6 73 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 74 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 75 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 76 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 77 9.1. Normative References . . . . . . . . . . . . . . . . . . 7 78 9.2. Informative References . . . . . . . . . . . . . . . . . 7 79 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 7 80 Appendix A. Implementations (to be removed by RFC Editor before 81 publication) . . . . . . . . . . . . . . . . . . . . 9 82 Appendix B. Change Log (to be removed by RFC Editor before 83 publication) . . . . . . . . . . . . . . . . . . . . 9 84 B.1. No previous version . . . . . . . . . . . . . . . . . . . 9 85 Appendix C. Resolved issues (to be removed by RFC Editor before 86 publication) . . . . . . . . . . . . . . . . . . . . 9 87 C.1. noPreviousVersion . . . . . . . . . . . . . . . . . . . . 9 88 Appendix D. Open issues (to be removed by RFC Editor prior to 89 publication) . . . . . . . . . . . . . . . . . . . . 9 90 D.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . 9 92 1. Introduction 94 HTTP 2xx status codes indicate that the client's request was 95 successfully received, understood, and accepted. The 2NN status code 96 response asserts that Location field identifies a resource related to 97 the requested resource and that the response contents are a 98 representation of that related resource. The 2NN response bypasses 99 the extra round trip required for use cases conventionally solved 100 with a 303 (See Other) response followed by the client performing a 101 second GET on the target of that redirect. For example, 2NN 102 streamlines these interactions which conventionally involve a server 103 response with a Location header referencing the information needed by 104 the client: 106 o An HTTP client performs a GET on a resource which is not an 107 information resource. The server responds with a 303 and the 108 client performs a second GET to retrieve an information resource 109 related to the previous resource. (This idiom is frequently used 110 to provide information about a resource while keeping that 111 resource distinct from any page describing it.) 113 o An HTTP server responds to a POST request by creating a new 114 resource and returning a 303 to redirect the client to that new 115 resource. (This use case is described in [8] .) 117 o The resource requested in a GET is prohibitively large to serve 118 and the server instead responds with a redirect to the beginning 119 of a series of resources paginating the initial resource. The 120 paginating resources are interlinked with the 'prev' and 'next' 121 link headers described in [9] . 123 o A client has requested a Web application and the server responds 124 with a multi-document response including e.g. HTML, images, CSS, 125 Javascript and data for the web application. 127 o A client performs a POST which creates a new resource. The server 128 has requested a Web application and the server responds with a 129 multi-document response including e.g. HTML, images, CSS, 130 Javascript and data for the web application. 132 2. Notational Conventions 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 136 document are to be interpreted as described in [RFC2119]. 138 3. 2NN Contents of Related 140 The 2NN (Contents of Related) status code indicates that the server 141 is providing a response for the request method (e.g. GET or POST) 142 performed on the URI in the Location header field, henceforth called 143 the "related resource". The "expected response" is the response that 144 the client would have received had it performed a GET on the related 145 resource. If the initial request method is HEAD, the expected 146 response has no message body (see RFC 7231 4.3.2. HEAD [10]). 148 By returning a 2NN status code, the server asserts that the expected 149 response has a status code of 200, and that its response (with the 150 2NN) is the same as the expected response with the status code 151 changed to 2NN and a Location header added to identify the related 152 resource. As with Content-Location, such a claim can only be trusted 153 if both identifiers share the same resource owner, which cannot be 154 programmatically determined via HTTP (see RFC 7231 3.1.4.2. Content- 155 Location [11]). 157 For caching purposes, see Section 3.1 below. For purposes other than 158 caching, the response is interpreted as if the response code were 200 159 and the effective request URI were the related resource. This 160 defines the semantics for all current headers other than Location, as 161 well as future headers defined as extensions to HTTP 1.1. A 2NN MUST 162 NOT be used if the expected response includes a Location header. 164 The following example demonstrates the use of 2NN responses to 165 streamline the creation of new resources as described by [LDP]. The 166 2NN response is generic; it can be used for any use case where the 167 server expects a client to dereference a Location header, for 168 example, image tiling or packaging web applications. 170 Client request: 172 GET /bigDoc HTTP/1.1 173 Host: bigco.example 174 Accept: text/turtle, q=1.0; application/rdf+xml, q=0.9 175 Prefer: contents-of-related 177 Server 2NN response: 179 HTTP/1.1 2NN Contents of Related 180 Content-Type: text/turtle 181 Location: http://bigco-static.example/p1 182 Link: ; rel="next" 183 Content-Location: http://bigco-static.example/p1.ttl 184 Content-Length: 145 186 187 "Here is everything we know about this giant resource...". 189 Here, the related resource is http://bigco-static.example/p1 and the 190 expected response is same as the Server 2NN response above, but with 191 a 200 status code and no Location header. The above example 192 communicates the same response as the following client-server 193 exchanges where the client performs on operation on a resource, the 194 server responds with a 303, and the client performs a GET (or HEAD) 195 on the resource in the Location header of the servers 303 response: 197 Client request: 199 GET /bigDoc HTTP/1.1 200 Host: bigco.example 201 Accept: text/turtle, q=1.0; application/rdf+xml, q=0.9 203 Server 303 response: 205 HTTP/1.1 303 See Related 206 Content-Type: text/html 207 Location: http://bigco-static.example/p1 208 Content-Length: 125 210 303

211 You probably want this. 212

214 Client request on the "related resource": 216 GET /p1 HTTP/1.1 217 Host: bigco.example 218 Accept: text/turtle, q=1.0; application/rdf+xml, q=0.9 220 Server response (defined as the "expected response"): 222 HTTP/1.1 200 OK 223 Content-Type: text/turtle 224 Link: ; rel="next" 225 Content-Location: http://bigco-static.example/p1.ttl 226 Content-Length: 145 228 229 "Here is everything we know about this giant resource...". 231 Note that in the Server 2NN response above, the Content-Location 232 provides a content-negotiated representation of the requested 233 resource and the Link provides paging information. Both illustrate 234 how a 2NN response header (other than Location) is interpreted as 235 applying to the resource in the Location header, http://bigco- 236 static.example/p1 in this example. 238 3.1. Caching Semantics 240 The client and any intervening proxies SHOULD cache the 2NN response 241 for the original effective request URI. If the client has out of 242 band reason to trust the server's claim that a GET performed on the 243 value of the Location header would have elicited the same response, 244 they may additionally cache a 200 response for a GET on value of the 245 Location header. 247 In the example Server 2NN response above, the client and intervening 248 proxies should cache the 2NN response to the GET of 249 http://bigco.example/bigDoc with the associated Accept header. If 250 the client has out of band knowledge that bigco.example has some 251 authority to answer for http://bigco-static.example/p1 and 252 http://bigco-static.example/p1.ttl , it may associate the expected 253 response with those resources as well. 255 4. contents-of-related Prefer header value 257 Per [12], this document registers the Prefer header ([RFC7240]) value 258 "contents-of-related". A client MAY include a "Prefer: contents-of- 259 related" header with a request to indicate that the client can accept 260 2NN responses. 262 5. Deployment Considerations 264 Section 4 of [13] specified that all 2xx status codes indicate a 265 successful request. However, some conventional clients may not be 266 specifically programmed to accept content accompanying a 2xx response 267 other than 200. Therefore, initial use of status code 2NN will be 268 restricted to cases where the server has sufficient confidence in the 269 clients understanding the new code. The contents-of-related Prefer 270 header value (see Section 4) is one way for the client to advertise 271 its support for 2NN responses. 273 6. Security Considerations 275 All security considerations that apply to either 303 or 200 response 276 codes apply also to the 2NN status code (see Section 12 of 277 [RFC7231]). Additionally, indiscriminately caching the 2NN response 278 as the response to the related resource permits malicious or 279 irresponsible servers to poison cache entries for 3rd parties. See 280 RFC 7231 [14] for similar constraints about associating cache entries 281 with the value of a Content-Location header. In particular, the 282 caching semantics including the warning "can only be trusted if both 283 identifiers share the same resource owner, which cannot be 284 programmatically determined via HTTP." 286 7. IANA Considerations 288 The registration below shall be added to the HTTP Status Code 289 Registry (defined in Section 4.2 of [RFC7231] and located at [15]): 291 +-------+---------------------+----------------------------------+ 292 | Value | Description | Reference | 293 +-------+---------------------+----------------------------------+ 294 | 2NN | Contents of Related | Section 3 of this specification | 295 +-------+---------------------+----------------------------------+ 297 8. Acknowledgements 299 The definition for the new status code 2NN re-uses text from the 300 HTTP/1.1 definitions of 2xx status codes. The structure and much of 301 the text of this draft was taken from [16]. John Arwe, Jenni 302 Tennison, and the W3C TAG and Linked Data Working Group for excellent 303 input and review. 305 9. References 307 9.1. Normative References 309 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 310 Requirement Levels", BCP 14, RFC 2119, March 1997. 312 [RFC7231] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 313 "HTTP/1.1, part 2: Message Semantics", RFC 7231, March 314 2012. 316 [RFC7240] Snell, J., Ed., "HTTP/1.1, part 2: Message Semantics", RFC 317 7240, June 2012. 319 9.2. Informative References 321 [LDP] Speicher, S., Ed., Arwe, J., Ed., and A. Malhotra, Ed., 322 "Linked Data Platform 1.0", W3C Candidate Recommendation 323 CR-ldp-20140619, June 2014, . 325 Latest version available at [17]. 327 9.3. URIs 329 [1] http://tools.ietf.org/html/rfc7231#section-6.4.4 331 [2] https://tools.ietf.org/html/rfc5005#section-3 333 [3] http://tools.ietf.org/html/rfc7231#section-4.3.2 335 [4] http://tools.ietf.org/html/rfc7231#section-3.1.4.2 337 [5] http://tools.ietf.org/html/rfc5226#section-5 339 [6] http://tools.ietf.org/html/rfc7231#section-3.1.4.2 341 [7] http://tools.ietf.org/html/rfc7231#section-3.1.4.2 343 [8] http://www.iana.org/assignments/http-status-codes 345 [9] http://tools.ietf.org/html/draft-reschke-http-status-308-07 347 Appendix A. Implementations (to be removed by RFC Editor before 348 publication) 350 @@Expected from W3C Linked Data Platform Working Group 352 Appendix B. Change Log (to be removed by RFC Editor before publication) 354 B.1. No previous version 356 ... 358 Appendix C. Resolved issues (to be removed by RFC Editor before 359 publication) 361 Issues that were either rejected or resolved in this version of this 362 document. 364 C.1. noPreviousVersion 366 no previous versions 368 ... 370 Appendix D. Open issues (to be removed by RFC Editor prior to 371 publication) 373 D.1. edit 375 Type: edit 377 eric@w3.org (2014-02-21): Umbrella issue for editorial fixes/ 378 enhancements. 380 Author's Address 382 Eric G. Prud'hommeaux 383 World Wide Web Consortium 384 32 Vassar St. 385 Cambridge, MA 02140 386 USA 388 EMail: eric@w3.org 389 URI: http://www.w3.org/People/Eric/ericP-foaf#ericP