Internet DRAFT - draft-prudhommeaux-http-status-2nn
draft-prudhommeaux-http-status-2nn
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: <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
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
<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.
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, <http://www.w3.org/turtle>.
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]
