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 (public archive) and the Linked Data Platform mailing list at public-ldp-comments@w3.org (public archive). The latter list may be joined by sending a message with subject "subscribe" to public-ldp-comments-request@w3.org.

XML versions, latest edits, and the issues list for this document are available from http://www.w3.org/2014/02/2xx/draft-prudhommeaux-http-status-2NN.

Test cases related to redirection in general and the status code 2NN in particular can be found at http://www.w3.org/2014/02/2xx/tests/ 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.

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. Notational Conventions
• 3. 2NN Contents of Related
• 3.1. Caching Semantics
• 4. contents-of-related Prefer header value
• 5. Deployment Considerations
• 6. Security Considerations
• 7. IANA Considerations
• 8. Acknowledgements
• 9. References
• 9.1. Normative References
• 9.2. Informative References
• Appendix A. Implementations (to be removed by RFC Editor before publication)
• 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)
• C.1. noPreviousVersion
• Appendix D. Open issues (to be removed by RFC Editor prior to publication)
• D.1. edit

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 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:

• 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.)
• 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 http://tools.ietf.org/html/rfc7231#section-6.4.4 .)
• 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 https://tools.ietf.org/html/rfc5005#section-3 .
• 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.
• 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 resource. If the initial request method is HEAD, the expected response has no message body (see RFC 7231 4.3.2. HEAD http://tools.ietf.org/html/rfc7231#section-4.3.2).

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 http://tools.ietf.org/html/rfc7231#section-3.1.4.2).

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: <http://bigco-static.example/p2>; rel="next"
  Content-Location: http://bigco-static.example/p1.ttl
  Content-Length: 145

  <http://bigco.example/bigDoc> <http://purl.org/dc/terms/description>
            "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 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

  <html><head><title>303</title></head><body><p>
  You probably want <a href="http://bigco-static.example/p1">this</a>.
  </p></body></html>
  

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: <http://bigco-static.example/p2>; rel="next"
  Content-Location: http://bigco-static.example/p1.ttl
  Content-Length: 145

  <http://bigco.example/bigDoc> <http://purl.org/dc/terms/description>
            "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.

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 http://tools.ietf.org/html/rfc5226#section-5, 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 http://tools.ietf.org/html/rfc7231#section-3.1.4.2 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 http://tools.ietf.org/html/rfc7231#section-3.1.4.2 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."

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 http://www.iana.org/assignments/http-status-codes):