Network Working Group E. Prud'hommeaux Internet-Draft W3C Intended status: Experimental June 30, 2014 Expires: January 1, 2015 The Hypertext Transfer Protocol (HTTP) Status Code 2NN (Contents of Related) draft-prudhommeaux-http-status-2nn-00 Abstract This document specifies the additional HyperText Transfer Protocol (HTTP) Status Code 2NN (Contents of Related). It also specified a Prefer header value "contents-of-related" which clients can use to indicate that they can accept 2NN responses. Editorial Note (To be removed by RFC Editor before publication) Distribution of this document is unlimited. Comments should be sent to the W3C Technical Architecture Group mailing list at www- tag@w3.org [1] (public archive [2]) and the Linked Data Platform mailing list at public-ldp-comments@w3.org [3] (public archive [4]). The latter list may be joined by sending a message with subject "subscribe" to public-ldp-comments-request@w3.org [5]. XML versions, latest edits, and the issues list for this document are available from [6]. Test cases related to redirection in general and the status code 2NN in particular can be found at [7] as a template. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on January 1, 2015. Prud'hommeaux Expires January 1, 2015 [Page 1] Internet-Draft HTTP Status Code 2NN June 2014 Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 3. 2NN Contents of Related . . . . . . . . . . . . . . . . . . . 3 3.1. Caching Semantics . . . . . . . . . . . . . . . . . . . . 6 4. contents-of-related Prefer header value . . . . . . . . . . . 6 5. Deployment Considerations . . . . . . . . . . . . . . . . . . 6 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 9.1. Normative References . . . . . . . . . . . . . . . . . . 7 9.2. Informative References . . . . . . . . . . . . . . . . . 7 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Appendix A. Implementations (to be removed by RFC Editor before publication) . . . . . . . . . . . . . . . . . . . . 9 Appendix B. Change Log (to be removed by RFC Editor before publication) . . . . . . . . . . . . . . . . . . . . 9 B.1. No previous version . . . . . . . . . . . . . . . . . . . 9 Appendix C. Resolved issues (to be removed by RFC Editor before publication) . . . . . . . . . . . . . . . . . . . . 9 C.1. noPreviousVersion . . . . . . . . . . . . . . . . . . . . 9 Appendix D. Open issues (to be removed by RFC Editor prior to publication) . . . . . . . . . . . . . . . . . . . . 9 D.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1. Introduction HTTP 2xx status codes indicate that the client's request was successfully received, understood, and accepted. The 2NN status code response asserts that Location field identifies a resource related to the requested resource and that the response contents are a Prud'hommeaux Expires January 1, 2015 [Page 2] Internet-Draft HTTP Status Code 2NN June 2014 representation of that related resource. The 2NN response bypasses the extra round trip required for use cases conventionally solved with a 303 (See Other) response followed by the client performing a second GET on the target of that redirect. For example, 2NN streamlines these interactions which conventionally involve a server response with a Location header referencing the information needed by the client: o An HTTP client performs a GET on a resource which is not an information resource. The server responds with a 303 and the client performs a second GET to retrieve an information resource related to the previous resource. (This idiom is frequently used to provide information about a resource while keeping that resource distinct from any page describing it.) o An HTTP server responds to a POST request by creating a new resource and returning a 303 to redirect the client to that new resource. (This use case is described in [8] .) o The resource requested in a GET is prohibitively large to serve and the server instead responds with a redirect to the beginning of a series of resources paginating the initial resource. The paginating resources are interlinked with the 'prev' and 'next' link headers described in [9] . o A client has requested a Web application and the server responds with a multi-document response including e.g. HTML, images, CSS, Javascript and data for the web application. o A client performs a POST which creates a new resource. The server has requested a Web application and the server responds with a multi-document response including e.g. HTML, images, CSS, Javascript and data for the web application. 2. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 3. 2NN Contents of Related The 2NN (Contents of Related) status code indicates that the server is providing a response for the request method (e.g. GET or POST) performed on the URI in the Location header field, henceforth called the "related resource". The "expected response" is the response that the client would have received had it performed a GET on the related Prud'hommeaux Expires January 1, 2015 [Page 3] Internet-Draft HTTP Status Code 2NN June 2014 resource. If the initial request method is HEAD, the expected response has no message body (see RFC 7231 4.3.2. HEAD [10]). By returning a 2NN status code, the server asserts that the expected response has a status code of 200, and that its response (with the 2NN) is the same as the expected response with the status code changed to 2NN and a Location header added to identify the related resource. As with Content-Location, such a claim can only be trusted if both identifiers share the same resource owner, which cannot be programmatically determined via HTTP (see RFC 7231 3.1.4.2. Content- Location [11]). For caching purposes, see Section 3.1 below. For purposes other than caching, the response is interpreted as if the response code were 200 and the effective request URI were the related resource. This defines the semantics for all current headers other than Location, as well as future headers defined as extensions to HTTP 1.1. A 2NN MUST NOT be used if the expected response includes a Location header. The following example demonstrates the use of 2NN responses to streamline the creation of new resources as described by [LDP]. The 2NN response is generic; it can be used for any use case where the server expects a client to dereference a Location header, for example, image tiling or packaging web applications. Client request: GET /bigDoc HTTP/1.1 Host: bigco.example Accept: text/turtle, q=1.0; application/rdf+xml, q=0.9 Prefer: contents-of-related Server 2NN response: HTTP/1.1 2NN Contents of Related Content-Type: text/turtle Location: http://bigco-static.example/p1 Link: ; rel="next" Content-Location: http://bigco-static.example/p1.ttl Content-Length: 145 "Here is everything we know about this giant resource...". Here, the related resource is http://bigco-static.example/p1 and the expected response is same as the Server 2NN response above, but with a 200 status code and no Location header. The above example Prud'hommeaux Expires January 1, 2015 [Page 4] Internet-Draft HTTP Status Code 2NN June 2014 communicates the same response as the following client-server exchanges where the client performs on operation on a resource, the server responds with a 303, and the client performs a GET (or HEAD) on the resource in the Location header of the servers 303 response: Client request: GET /bigDoc HTTP/1.1 Host: bigco.example Accept: text/turtle, q=1.0; application/rdf+xml, q=0.9 Server 303 response: HTTP/1.1 303 See Related Content-Type: text/html Location: http://bigco-static.example/p1 Content-Length: 125 303

You probably want this.

Client request on the "related resource": GET /p1 HTTP/1.1 Host: bigco.example Accept: text/turtle, q=1.0; application/rdf+xml, q=0.9 Server response (defined as the "expected response"): HTTP/1.1 200 OK Content-Type: text/turtle Link: ; rel="next" Content-Location: http://bigco-static.example/p1.ttl Content-Length: 145 "Here is everything we know about this giant resource...". Note that in the Server 2NN response above, the Content-Location provides a content-negotiated representation of the requested resource and the Link provides paging information. Both illustrate how a 2NN response header (other than Location) is interpreted as applying to the resource in the Location header, http://bigco- static.example/p1 in this example. Prud'hommeaux Expires January 1, 2015 [Page 5] Internet-Draft HTTP Status Code 2NN June 2014 3.1. Caching Semantics The client and any intervening proxies SHOULD cache the 2NN response for the original effective request URI. If the client has out of band reason to trust the server's claim that a GET performed on the value of the Location header would have elicited the same response, they may additionally cache a 200 response for a GET on value of the Location header. In the example Server 2NN response above, the client and intervening proxies should cache the 2NN response to the GET of http://bigco.example/bigDoc with the associated Accept header. If the client has out of band knowledge that bigco.example has some authority to answer for http://bigco-static.example/p1 and http://bigco-static.example/p1.ttl , it may associate the expected response with those resources as well. 4. contents-of-related Prefer header value Per [12], this document registers the Prefer header ([RFC7240]) value "contents-of-related". A client MAY include a "Prefer: contents-of- related" header with a request to indicate that the client can accept 2NN responses. 5. Deployment Considerations Section 4 of [13] specified that all 2xx status codes indicate a successful request. However, some conventional clients may not be specifically programmed to accept content accompanying a 2xx response other than 200. Therefore, initial use of status code 2NN will be restricted to cases where the server has sufficient confidence in the clients understanding the new code. The contents-of-related Prefer header value (see Section 4) is one way for the client to advertise its support for 2NN responses. 6. Security Considerations All security considerations that apply to either 303 or 200 response codes apply also to the 2NN status code (see Section 12 of [RFC7231]). Additionally, indiscriminately caching the 2NN response as the response to the related resource permits malicious or irresponsible servers to poison cache entries for 3rd parties. See RFC 7231 [14] for similar constraints about associating cache entries with the value of a Content-Location header. In particular, the caching semantics including the warning "can only be trusted if both identifiers share the same resource owner, which cannot be programmatically determined via HTTP." Prud'hommeaux Expires January 1, 2015 [Page 6] Internet-Draft HTTP Status Code 2NN June 2014 7. IANA Considerations The registration below shall be added to the HTTP Status Code Registry (defined in Section 4.2 of [RFC7231] and located at [15]): +-------+---------------------+----------------------------------+ | Value | Description | Reference | +-------+---------------------+----------------------------------+ | 2NN | Contents of Related | Section 3 of this specification | +-------+---------------------+----------------------------------+ 8. Acknowledgements The definition for the new status code 2NN re-uses text from the HTTP/1.1 definitions of 2xx status codes. The structure and much of the text of this draft was taken from [16]. John Arwe, Jenni Tennison, and the W3C TAG and Linked Data Working Group for excellent input and review. 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC7231] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., "HTTP/1.1, part 2: Message Semantics", RFC 7231, March 2012. [RFC7240] Snell, J., Ed., "HTTP/1.1, part 2: Message Semantics", RFC 7240, June 2012. 9.2. Informative References [LDP] Speicher, S., Ed., Arwe, J., Ed., and A. Malhotra, Ed., "Linked Data Platform 1.0", W3C Candidate Recommendation CR-ldp-20140619, June 2014, . Latest version available at [17]. 9.3. URIs [1] http://tools.ietf.org/html/rfc7231#section-6.4.4 [2] https://tools.ietf.org/html/rfc5005#section-3 [3] http://tools.ietf.org/html/rfc7231#section-4.3.2 Prud'hommeaux Expires January 1, 2015 [Page 7] Internet-Draft HTTP Status Code 2NN June 2014 [4] http://tools.ietf.org/html/rfc7231#section-3.1.4.2 [5] http://tools.ietf.org/html/rfc5226#section-5 [6] http://tools.ietf.org/html/rfc7231#section-3.1.4.2 [7] http://tools.ietf.org/html/rfc7231#section-3.1.4.2 [8] http://www.iana.org/assignments/http-status-codes [9] http://tools.ietf.org/html/draft-reschke-http-status-308-07 Prud'hommeaux Expires January 1, 2015 [Page 8] Internet-Draft HTTP Status Code 2NN June 2014 Appendix A. Implementations (to be removed by RFC Editor before publication) @@Expected from W3C Linked Data Platform Working Group Appendix B. Change Log (to be removed by RFC Editor before publication) B.1. No previous version ... Appendix C. Resolved issues (to be removed by RFC Editor before publication) Issues that were either rejected or resolved in this version of this document. C.1. noPreviousVersion no previous versions ... Appendix D. Open issues (to be removed by RFC Editor prior to publication) D.1. edit Type: edit eric@w3.org (2014-02-21): Umbrella issue for editorial fixes/ enhancements. Author's Address Eric G. Prud'hommeaux World Wide Web Consortium 32 Vassar St. Cambridge, MA 02140 USA EMail: eric@w3.org URI: http://www.w3.org/People/Eric/ericP-foaf#ericP Prud'hommeaux Expires January 1, 2015 [Page 9]