action-127 use tag [23]xx status code for paging; also change paging to be for LDP-RRs as a consequence of issue-89 vocab changes
authorJohn Arwe
Thu, 06 Feb 2014 13:14:15 -0500
changeset 464 77fd28c9eb94
parent 463 ae72388dbb82
child 465 26eb1d6d4fd6
action-127 use tag [23]xx status code for paging; also change paging to be for LDP-RRs as a consequence of issue-89 vocab changes
ldp.html
--- a/ldp.html	Thu Feb 06 10:11:25 2014 -0500
+++ b/ldp.html	Thu Feb 06 13:14:15 2014 -0500
@@ -238,7 +238,7 @@
 	</p> 
 	<p>This specification provides a widely re-usable pattern to deal with large resources.  
 	Depending on the server’s capabilities, a GET request on a <a title="Paged resource">resource</a> can
-	return a <a title="Single-page resource">subset of the resource (one page)</a>, that provides access to subsequent pages 
+	be redirected to a <a title="Single-page resource">subset of the resource (one page)</a>, that provides access to subsequent pages 
 	(see <a href="#ldpr-Paging" class="sectionRef"></a>). 
 	</p>
 	<p>This specification defines a special type of <a>Linked Data Platform Resource</a>: a 
@@ -376,14 +376,16 @@
 	<p></p></dd>
 	
 	<dt><dfn>Paged resource</dfn></dt>
-	<dd>A resource whose representation may be too large to fit in a single HTTP response, for which an
-	LDP server offers a sequence of single-page resources.  When the representations of the sequence's resources
+	<dd>A LDP-RR whose representation may be too large to fit in a single HTTP response, for which an
+	LDP server offers a sequence of single-page <a title="Linked Data Platform RDF Resource">LDP-RRs</a>.  
+	When the representations of the sequence's resources
 	are combined by a client, the client has a (potentially incomplete or incoherent) copy of the paged resource's
-	state.  If a paged resource <var>P</var> is an LDPR and is broken into a sequence of pages
+	state.  If a paged resource <var>P</var> is a LDP-RR and is broken into a sequence of pages
 	(single-page resources) <var>P<sub>1</sub>, P<sub>2</sub>, ...,P<sub>n</sub></var>,
 	the representation of each <var>P<sub>i</sub></var> contains
 	a subset of the triples in <var>P</var>.
-	LDP allows paging of resources other than LDPRs, but does not specify how clients combine
+	LDP allows paging of resources other than <a title="Linked Data Platform RDF Resource">LDP-RRs</a>, 
+	but does not specify how clients combine
 	their representations.  See <a href="#ldpr-Paging" class="sectionRef"></a> for additional details.  For readers
 	familiar with paged feeds [[RFC5005]], a paged resource is similar to a logical feed.
 	Any resource could be considered to be a paged resource consisting of exactly one page, 
@@ -391,7 +393,8 @@
 	<p></p></dd>
 	
 	<dt><dfn>Single-page resource</dfn></dt>
-	<dd>One of a sequence of related resources <var>P<sub>1</sub>, P<sub>2</sub>, ...,P<sub>n</sub></var>, 
+	<dd>One of a sequence of related <a title="Linked Data Platform RDF Resource">LDP-RRs</a>
+	<var>P<sub>1</sub>, P<sub>2</sub>, ...,P<sub>n</sub></var>, 
 	each of which contains a subset of the state
 	of another resource <var>P</var>.  <var>P</var> is called the paged resource.
 	For readers
@@ -531,7 +534,7 @@
 				such as type changes?</li>
 		<li>What can servers do to ease the burden of constraints for resource
 				creation?</li>
-		<li>How	do I GET the entries of a large resources broken up into pages?</li>
+		<li>How	do I GET the representation of a large resource broken up into pages?</li>
 	</ul>
 	<p>Additional non-normative guidance is available in the <a
 			href="https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp-bp/ldp-bp.html"
@@ -544,7 +547,7 @@
 		<li>Are there some typical vocabularies that should be reused?</li>
 	</ul>
 	<p>The following sections define the conformance rules for LDP servers when serving LDPRs.
-		This document also explains <a href="#ldpr-Paging">how a server paginates an LDPR's representation</a> if it gets too big.
+		This document also explains <a href="#ldpr-Paging">how a server paginates an LDP-RR's representation</a> if it gets too big.
 		Companion non-normative documents describe additional guidelines for use when interacting with LDPRs. 
 	</p>
 	<p>An LDP server manages two kinds of <a title="Linked Data Platform Resources">LDPRs</a>, those resources who whose state 
@@ -660,13 +663,13 @@
 		although machine-readable ones facilitate better client interactions.
 	</h2></section><!-- Was 4.2.13 / #ldpr-4_2_13 -->
 	
-	<section id="ldpr-page-large"><h2 class="normal"><a title="LDP server">LDP servers</a> SHOULD allow clients to retrieve large LDPRs in
+	<section id="ldpr-page-large"><h2 class="normal"><a title="LDP server">LDP servers</a> SHOULD allow clients to retrieve large LDP-RRs in
 		pages.
 		See <a href="#ldpr-Paging" class="sectionRef"></a> for additional requirements associated with <a title="Paged resource">paged resources</a>.
 	</h2></section><!-- Was 4.2.14 / #ldpr-4_2_14 -->
 	
 	<section id="ldpr-split-any"><h2 class="normal"><a title="LDP server">LDP servers</a> MAY 
-		treat any resource (LDPR or not) as a <a title="Paged resource">paged resource</a>. 
+		treat any resource (LDP-RR or not) as a <a title="Paged resource">paged resource</a>. 
 		See <a href="#ldpr-Paging" class="sectionRef"></a> for additional details.
 	</h2></section><!-- Was 4.2.15 / #ldpr-4_2_15 -->
 
@@ -833,37 +836,19 @@
 
 <section class="informative" id="ldpr-PagingIntro">
 
-	<div class="atrisk"><p class="atrisktext">Feature At Risk</p>
-		<p>The LDP Working Group proposes incorporation of the features described in this section.</p>
-		<ul>
-		<li>There is a <a href="http://lists.w3.org/Archives/Public/www-tag/2013Dec/0041.html">TAG discussion</a>
-		whose goal is to reduce the need for two request-response round trips down to one, by defining a new
-		HTTP response code in the <code>2xx</code> or <code>3xx</code> class that would allow a server to
-		respond to <code>GET request-uri</code> requests with the representation of the first page 
-		(whose URI is <code>first-page-uri</code>, not <code>request-uri</code>) of a multi-page response.
-		<p>Once LDP is in
-		Candidate Recommendation, the LDP WG will make an assessment based on the status at IETF
-		working with the W3C Director to either use the newly defined response code 
-		as documented in this section or to revert to a classic 
-		<code>303</code> response pattern.
-		</p>
-		</li>
-		</ul>
-	</div>
-		
 <h3>Introduction</h3>
 	<p>It sometimes happens that a
 		resource is too large to reasonably transmit its representation in a
 		single HTTP response.  
 		To address this problem, servers should support a technique called Paging.  
-		When a client retrieves such a resource, the server includes in its response
-		a link to the next part of the resource's state, at a URL of the server's choosing.
+		When a client retrieves such a resource, the server redirects the client to a "first page" resource, and includes in its response
+		a link to the next part of the resource's state, all at a URLs of the server's choosing.
 		The triples in the representation of the <a title="Single-page resource">each page of an LDPR</a>
 		are typically a subset of the triples from the <a title="Paged resource">paged resource</a>.
 	</p>
 	<p><a title="LDP server">LDP servers</a> may respond to requests for a
-		resource by returning the first page of the resource
-		with a <code>Link &lt;next-page-URL&gt;;type='next'</code> header containing the URL for the next page.
+		resource by redirecting to the first page of the resource and, with that, returning 
+		a <code>Link &lt;next-page-URL&gt;;type='next'</code> header containing the URL for the next page.
 		Clients inspect each response for the link header to see if additional pages
 		are available; paging does not affect the choice of HTTP status code.
 		Note that paging is lossy, as described in [[RFC5005]], and so (as stated there)
@@ -875,11 +860,13 @@
 		we’ll split the response across two pages.  
 		The client 
 		retrieves <code>http://example.org/customer-relations</code>, and
-		the server responds with status code 200 (OK) and the following representation:
+		the server responds with <a href="#atrisk-333">status code <code>333 (Returning Related)</code></a>, 
+		a <code>Location: http://example.org/customer-relations?page1</code> HTTP response header,
+		and the following representation:
 	</p>
 
 <pre class="example" id="ldpc-ex-page1"># The following is the representation of
-#    http://example.org/customer-relations
+#    http://example.org/customer-relations?page1
 #    Requests on the URI will result in responses that include the following HTTP header
 #       Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='next'
 #    This Link header is how clients discover the URI of the next page in sequence,
@@ -911,7 +898,8 @@
 
 	<p>
 		Because the server includes a <code>Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='next'</code>
-		response header, the client knows that more data exists and where to find it.
+		response header, and the status code is 3xx (<code>333 (Returning Related)</code> in this case), 
+		the client knows that more data exists and where to find it.
 		The server determines the size of the pages using application specific methods not defined
 		within this specificiation. The next page link's target URI is also
 		defined by the server and not this specification.
@@ -919,7 +907,7 @@
 	<p>
 		The following example is the result of retrieving
 		the next page; 
-		the server responds with status code 200 (OK) and the following representation:
+		the server responds with status code <code>200 (OK)</code> and the following representation:
 	</p>
 
 <pre class="example" id="ldpc-ex-page2"># The following is the representation of
@@ -1034,6 +1022,43 @@
 		as the <code>Request-URI</code>.
 		This is one mechanism by which clients know that the resource is one of a sequence of pages.  
 	</h2></section><!-- Was 4.10.2.4 / #ldpr-pagingGET-page-type-reqd -->
+
+	<div class="atrisk" id="atrisk-333"><p class="atrisktext">Feature At Risk</p>
+		<p>The LDP Working Group proposes incorporation of the features described in the next compliance clause.</p>
+		<ul>
+		<li><p>
+		A <a href="http://lists.w3.org/Archives/Public/www-tag/2013Dec/0041.html">TAG discussion</a> has started,
+		whose goal is to reduce the need for two request-response round trips down to one when retrieving what 
+		turns out to be the first page of a paged resource, by defining a new
+		HTTP response code in the <code>2xx</code> or <code>3xx</code> class that would allow a server to
+		respond to <code>GET request-uri</code> requests with the representation of the first page 
+		(whose URI is <code>first-page-uri</code>, not <code>request-uri</code>) of a multi-page response.
+		</p></li>
+		<li><p>
+		For the purposes of drafting this section, we assume that the 
+		new code's value is <code>333 (Returning Related)</code>,
+		<a href="http://lists.w3.org/Archives/Public/www-tag/2014Jan/0023.html">an LDP extrapolation from TAG discussions,</a>
+		and its definition is given by 
+		<a href="http://lists.w3.org/Archives/Public/www-tag/2014Jan/0015.html">Henry Thompson's strawman</a>, with the substitution of 333 for 2xx.
+		Note: nothing prevents servers or clients from using <code>303 See Other</code> responses to 
+		requests for <a title="Paged resource">paged resources</a>.  The only significant difference between 303 and 333 responses
+		is the extra round trip required for the client to retrieve the representation of the first page when using 303.
+		</p></li>
+		<li><p>
+		Once LDP is a
+		Candidate Recommendation, the LDP WG will make an assessment based on the status at IETF,
+		working with the W3C Director, to either use the newly defined response code 
+		as documented in this section or to revert to a classic 
+		<code>303</code> response pattern.
+		</p></li>
+		</ul>
+	</div>
+		
+	<section id="ldpr-status-code"><h2 class="normal"><a title="LDP server">LDP servers</a> SHOULD respond 
+		with HTTP status code <code>333 (Returning Related)</code> 
+		to successful <code>GET</code> requests with any <a title="Paged resource">paged resource</a> 
+		as the <code>Request-URI</code>, although any appropriate code MAY be used.
+	</h2></section>
 </section>
 
 <section id="ldpr-paging-HTTP_OPTIONS">
@@ -1048,6 +1073,8 @@
 		less than is required for HTTP <code>GET</code>.  
 		This lowers server implementation effort.
 	</p>
+	
+	<!-- TODO: This section is empty - looks weird, and it is linked to from other sections -->
 
 </section> <!-- h3 -->
 
@@ -2252,7 +2279,7 @@
 <!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130930/">Candidate Recommendation Draft</a></em></blockquote> wah -->
 <!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130730/">Last Call Draft</a></em></blockquote> -->
 <ul>
-	<li>2014-02-06 - ACTION-127 (still WIP) use the TAG's new [23]xx code; if that code is not sufficiently through IETF process by CR, we will use a 303 (JA)</li>
+	<li>2014-02-06 - ACTION-127 (complete) use the TAG's new [23]xx code; if that code is not sufficiently through IETF process by CR, we will use a 303 (JA)</li>
 	<li>2014-02-05 - ACTION-133 Get rid of ldp:created which is subsumed by ldp:contains (SS)</li>
 	<li>2014-02-04 - ACTION-124 LDPR-RR as named graphs  (SS)</li>
 	<li>2014-02-04 - ACTION-120 (complete) Updated LDPC general, GET and POST sections (SS)</li>