Resolve ACTION-113 Update spec to reflect 11/04 resolution to remove 303 and have client use first/next links to detect paging
authorJohn Arwe
Mon, 11 Nov 2013 16:33:38 -0500
changeset 412 b5f309858d98
parent 411 ee213bae0933
child 413 55af75032d16
Resolve ACTION-113 Update spec to reflect 11/04 resolution to remove 303 and have client use first/next links to detect paging
ldp.html
--- a/ldp.html	Thu Nov 07 15:29:34 2013 -0500
+++ b/ldp.html	Mon Nov 11 16:33:38 2013 -0500
@@ -133,6 +133,15 @@
 					]
 				,   status:   "Proposed Standard"
 				,   publisher:  "IETF"
+				},
+				"RFC5005": {
+					title:    "Feed Paging and Archiving"
+				,   href:     "http://tools.ietf.org/html/rfc5005"
+				,   authors:  [
+						"M. Nottingham"
+					]
+				,   status:   "Proposed Standard"
+				,   publisher:  "IETF"
 				}
 			},
       };
@@ -317,22 +326,35 @@
 	<dd>The predicate of all a LDPC's <a title="Membership triples">membership triples</a>.
 	<p></p></dd>
 	
+	<dt><dfn>Non-member resource</dfn></dt>
+	<dd>A resource associated with a LDPC by a server for the purpose of enabling clients to
+	retrieve a subset of the LDPC's state, namely the subset that omits the LDPC's membership triples.
+	In other words, the union of the non-member resource's state and the LDPC's membership triples
+	exactly equals the LDPC's state.
+	<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
-	are combined by a client, the client has a (potentially incomplete) copy of the paged resource's
+	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
 	(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
-	their representations.  See <a href="#ldpr-Paging" class="sectionRef"></a> for additional details.
+	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 non-paged resource could be considered to be a paged resource consisting of exactly one page, 
+	although there is no known advantage in doing so.
 	<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>, 
 	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
+	familiar with paged feeds [[!RFC5005]], a single-page resource is similar to a feed document and the same
+	coherency/completeness considerations apply.
 	</p><p>
 	Note: the choice of terms was designed to help authors and readers clearly differentiate between
 	the <a title="Paged resource"><em>resource being paged</em></a>, and the 
@@ -341,11 +363,32 @@
 	close proximity.  Both are resources in both the HTTP and RDF senses.
 	<p></p></dd>
 	
-	<dt><dfn>Non-member resource</dfn></dt>
-	<dd>A resource associated with a LDPC by a server for the purpose of enabling clients to
-	retrieve a subset of the LDPC's state, namely the subset that omits the LDPC's membership triples.
-	In other words, the union of the non-member resource's state and the LDPC's membership triples
-	exactly equals the LDPC's state.
+	<dt><dfn>first page link</dfn></dt>
+	<dd>A link to the first <a title="Single-page resource">single-page resource</a>
+	of a <a title="Paged resource">paged resource</a> <var>P</var>.  Syntactically, a
+	HTTP <code>Link &lt;<var>P<sub>1</sub></var>&gt;; rel='first'</code>
+	header [[!RFC5988]].
+	<p></p></dd>
+	
+	<dt><dfn>next page link</dfn></dt>
+	<dd>A link to the next <a title="Single-page resource">single-page resource</a> 
+	of a <a title="Paged resource">paged resource</a> <var>P</var>.  Syntactically, a
+	HTTP <code>Link &lt;<var>P<sub>i</sub></var>&gt;; rel='next'</code>
+	header [[!RFC5988]] where <var>i=2...n</var>.
+	<p></p></dd>
+	
+	<dt><dfn>last page link</dfn></dt>
+	<dd>A link to the last <a title="Single-page resource">single-page resource</a>
+	of a <a title="Paged resource">paged resource</a> <var>P</var>.  Syntactically, a
+	HTTP <code>Link &lt;<var>P<sub>n</sub></var>&gt;; rel='last'</code>
+	header [[!RFC5988]].
+	<p></p></dd>
+	
+	<dt><dfn>previous page link</dfn></dt>
+	<dd>A link to the previous <a title="Single-page resource">single-page resource</a> 
+	of a <a title="Paged resource">paged resource</a> <var>P</var>.  Syntactically, a
+	HTTP <code>Link &lt;<var>P<sub>i</sub></var>&gt;; rel='prev'</code>
+	header [[!RFC5988]] where <var>i=1...n-1</var>.
 	<p></p></dd>
 	
   </dl>
@@ -804,50 +847,35 @@
 <h3>Introduction</h3>
 	<p>It sometimes happens that a
 		resource is too large to reasonably transmit its representation in a
-		single HTTP response. This will be especially true if the resource
-		is a container whose
-		representation includes many triples both from itself  and
-		from its member resources. A client could anticipate that a resource will be too large -
-		for example, a client tool that accesses defects may assume that an
-		individual defect will usually be of sufficiently constrained size
-		that it makes sense to request all of it at once, but that the
-		container of all the defects ever created will typically be too big.
-		Alternatively, a server could recognize that a resource that has been
-		requested is too big to return in a single message.</p>
-	<p>
-		To address this problem, resources should support a technique called Paging.  Paging can be achieved with a
-		simple pattern. For each resource, <code>&lt;resourceURL&gt;</code>, we define a new
-		'first page' resource.  In this example, its URL will be <code>&lt;resourceURL&gt;?firstPage</code>,
-		but servers are free to construct the URL as they see fit.
+		single HTTP response.  
+		To address this problem, resources 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.
 		The triples in the representation of the each page of an LDPR
-		are typically a subset of the triples in the resource
-		- same subject, predicate and object.
+		are typically a subset of the triples in the resource.
 	</p>
 	<p><a title="LDP server">LDP servers</a> may respond to requests for a
-		resource by returning the first page resource –
-		using a <a href="#status-code-related-content"><code>209 Related Content</code></a> response
-		with a <code>Location</code> header containing the URL for the page
-		resource.  Alternatively, clients may inspect the resource for a paged representation 
-		and use it preferentially when available.</p>
+		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.
+		Clients inspect each response to see if additional pages
+		are available.  Note that paging is lossy, as described in [[RFC5005]], and so (as stated there)
+		clients should not make any assumptions about a set of pages being a complete or 
+		coherent snapshot of a resource's state.</p>
 	<p>
 		Looking at an example resource representing Example Co.'s customer
 		relationship data, identified by the URI <code>http://example.org/customer-relations</code>,
 		we’ll split the response across two pages.  
-		To find out if the resource supports paging, and if it does the URL of the first page, 
-		the client makes a <code>OPTIONS</code> or <code>HEAD</code> request
-		to <code>http://example.org/customer-relations</code>, and in the response looks for a HTTP <code>Link</code>
-		header with <code>rel='first'</code>; the target URI in the header is the URL
-		of the first page resource.
-		The client then 
-		requests the first page as <code>http://example.org/customer-relations?firstPage</code>, and
+		The client 
+		retrieves the first page of <code>http://example.org/customer-relations</code>, and
 		the server responds with the following representation:
 	</p>
 
 <pre class="example"># The following is the representation of
-#    http://example.org/customer-relations?firstPage
+#    http://example.org/customer-relations
 #    Requests on the ?firstPage 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.
+#    This Link header is how clients discover the URI of the next page in sequence,
+#    and that the resource supports paging.
 @prefix rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
 @prefix dcterms: &lt;http://purl.org/dc/terms/&gt;.
 @prefix foaf: &lt;http://xmlns.com/foaf/0.1/&gt;.
@@ -910,6 +938,12 @@
 		final page.  To indicate this is the last page, the server omits the <code>Link rel='next'</code> 
 		header in its response.
 	</p>
+	<p>
+		As mentioned above, retrieving all the pages offered by a server gives no guarantee to a client
+		that it knows the entire state of the server.  For example, after the server constructs the
+		the first page representation, another
+		actor could delete <code>client#BettyASmith</code> from the server.  
+	</p>
 </section>
 
 <section id="ldpr-PagingGET">
@@ -920,7 +954,10 @@
 		and their associated <a title="Single-page resource">single-page resources</a>.
 	</p>
 
-	<div id="ldpr-pagingGET-first-reqd-onbase" class="rule">4.10.2.1 <a title="LDP server">LDP servers</a> MUST
+	<div id="ldpr-pagingGET-first-reqd-onbase" class="rule">4.10.2.1 removed
+	</div>
+	<!-- Removed - action-113
+	<div id="ldpr-pagingGET-first-reqd-onbase" class="rule">4.10.2.1 <a title="LDP server">LDP servers</a> MAY
 		provide an HTTP <code>Link</code>
 		header whose target URI is the <em>first</em> <a title="Single-page resource">single-page resource</a>, and whose link relation type is <code>first</code> [[!RFC5988]]
 		in responses to <code>GET</code> requests with a <a title="Paged resource">paged resource</a> as the <code>Request-URI</code>.
@@ -932,11 +969,15 @@
 		then clients have no LDP-defined way to discover that the resource supports paging or the
 		URI of the first page.
 	</div>
+	-->
 	<div id="ldpr-pagingGET-first-allowed-onpages" class="rule">4.10.2.1.1 
 		<a title="LDP server">LDP servers</a> MAY provide 
-		a <a href="#ldpr-pagingGET-first-reqd-onbase">first page link</a> when responding to 
-		requests with any <a title="Single-page resource">single-page resource</a> as the <code>Request-URI</code>.
+		a <a>first page link</a> when responding to 
+		requests with any <a>single-page resource</a> as the <code>Request-URI</code>.
 	</div>
+	<div id="ldpr-pagingGET-last-allowed-onbase" class="rule">4.10.2.1.2 removed
+	</div>
+	<!-- Removed - action-113
 	<div id="ldpr-pagingGET-last-allowed-onbase" class="rule">4.10.2.1.2 <a title="LDP server">LDP servers</a> MAY
 		provide an HTTP <code>Link</code>
 		header whose target URI is the final <a title="Single-page resource">single-page resource</a>, 
@@ -949,38 +990,43 @@
 		then clients can only find the final page using LDP-defined means 
 		by following the <code>next</code> links to the end.
 	</div>
+	-->
 	<div id="ldpr-pagingGET-last-allowed-onpages" class="rule">4.10.2.1.3 <a title="LDP server">LDP servers</a> MAY
-		provide a <a href="#ldpr-pagingGET-last-allowed-onbase">last page link</a>
+		provide a <a>last page link</a>
 		in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a> as the <code>Request-URI</code>.
 	</div>
 	<div id="ldpr-pagingGET-next-reqd" class="rule">4.10.2.2 <a title="LDP server">LDP servers</a> MUST
-		provide an HTTP <code>Link</code>
-		header whose target URI is the next page resource, and whose link relation type is <code>next</code> [[!RFC5988]]
+		provide a <a>next page link</a>
 		in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a> 
 		<em>other than the final page</em>
 		as the <code>Request-URI</code>.
 		This is the mechanism by which clients can discover the URL of the next page. 
 	</div>
 	<div id="ldpr-pagingGET-lastnext-prohibited" class="rule">4.10.2.2.1 <a title="LDP server">LDP servers</a> MUST NOT
-		provide a <a href="#ldpr-pagingGET-next-reqd">next page link</a> 
+		provide a <a>next page link</a>
 		in responses to <code>GET</code> requests with the final <a title="Single-page resource">single-page resource</a> 
 		as the <code>Request-URI</code>.
-		This is the mechanism by which clients can discover the end of the page sequence.
+		This is the mechanism by which clients can discover the end of the page sequence
+		as currently known by the server.  The server is permitted to append pages over time,
+		so clients retrieving a final page several times can observe a "formerly last" page
+		having a <a>next page link</a> added.
 	</div>
 	<div id="ldpr-pagingGET-prev-allowed" class="rule">4.10.2.2.2 <a title="LDP server">LDP servers</a> MAY
-		provide an HTTP <code>Link</code>
-		header whose target URI is the previous page resource, and whose link relation type is <code>prev</code> [[!RFC5988]]
+		provide a <a>previous page link</a>
 		in responses to <code>GET</code> requests with any page resource <em>other than the first page</em>
 		as the <code>Request-URI</code>.
 		This is one mechanism by which clients can discover the URL of the previous page.  
 	</div>
 	<div id="ldpr-pagingGET-firstprev-prohibited" class="rule">4.10.2.2.3 <a title="LDP server">LDP servers</a> MUST NOT
-		provide a <a href="#ldpr-pagingGET-prev-reqd">previous page link</a> 
+		provide a <a>previous page link</a>
 		in responses to <code>GET</code> requests with the <em>first</em> <a title="Single-page resource">single-page resource</a> 
 		as the <code>Request-URI</code>.
 		This is one mechanism by which clients can discover the beginning of the page sequence.
 	</div>
-	<div id="ldpr-pagingGET-next-reqd" class="rule">4.10.2.2.4 <a title="LDP server">LDP servers</a> MUST
+	<div id="ldpr-pagingGET-collection-reqd" class="rule">4.10.2.2.4 removed
+	</div>
+	<!-- Removed - action-113
+	<div id="ldpr-pagingGET-collection-reqd" class="rule">4.10.2.2.4 <a title="LDP server">LDP servers</a> MUST
 		provide an HTTP <code>Link</code>
 		header whose target URI is the <a title="Paged resource">paged resource</a>, and whose link relation type is <code>collection</code> [[!RFC5988]]
 		in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a> 
@@ -989,11 +1035,16 @@
 		has been broken into pages, in cases where some other actor gives the client 
 		a <a title="Single-page resource">single-page resource</a> URL. 
 	</div>
+	-->
+	<div id="ldpr-pagingGET-redirect" class="rule">4.10.2.3 removed
+	</div>
+	<!-- Removed - action-113
 	<div id="ldpr-pagingGET-redirect" class="rule">4.10.2.3 <a title="LDP server">LDP servers</a> 
 		that initiate paging for a LDPR MUST respond 
 		by returning the first page resource using a <code>209 Related Content</code> response 
 		with an HTTP <code>Location</code> header providing the first <a title="Single-page resource">single-page resource</a> URL.
 	</div>
+	-->
 	<div id="ldpr-pagingGET-page-type-reqd" class="rule">4.10.2.4 <a title="LDP server">LDP servers</a> MUST
 		provide an HTTP <code>Link</code>
 		header whose target URI is <code>http://www.w3.org/ns/ldp#Page</code>, and whose link relation type is <code>type</code> [[!RFC5988]]
@@ -1016,10 +1067,14 @@
 		This lowers server implementation effort.
 	</p>
 
+	<div id="ldpr-4_10_3_1" class="rule">4.10.3.1 removed
+	</div>
+	<!-- Removed - action-113
 	<div id="ldpr-4_10_3_1" class="rule">4.10.3.1 <a title="LDP server">LDP servers</a> MUST indicate their support for paging by
 		providing a <a href="#ldpr-pagingGET-first-reqd-onbase">first page link</a> when responding to HTTP <code>OPTIONS</code> 
 		requests with a <a title="Paged resource">paged resource</a> as the <code>Request-URI</code>.
 	</div>
+	-->
 
 </section> <!-- h3 -->
 
@@ -1980,7 +2035,7 @@
 		are used in the state of any one resource is not limited to any pre-defined
 		set.
 	</div>
-	<div id="ldpr-4_5_5" class="rule">4.5.5 An <a title="LDP client">LDP client</a> MUST preserve all triples retrieved using HTTP <code>GET</code> that
+	<div id="ldpr-4_5_5" class="rule">4.5.5 A <a title="LDP client">LDP client</a> MUST preserve all triples retrieved using HTTP <code>GET</code> that
 		it doesn’t change whether it understands the predicates or not, when
 		its intent is to perform an update using HTTP <code>PUT</code>.  The use of HTTP
 		<code>PATCH</code> instead of HTTP <code>PUT</code> for update avoids this burden for clients
@@ -2091,6 +2146,17 @@
 
 </section> 
 
+<section id="specs-paging" class="informative">
+<h1>Feed paging and archiving</h1>
+Reference: [[RFC5005]]
+
+	<div id="ldp-paging-incomplete" class="rule">9.4.1 A <a title="LDP client">LDP client</a>  
+		SHOULD NOT present <a title="paged resource">paged resources</a> as coherent or
+		complete, or make assumptions to that effect.
+		[[RFC5005]].
+	</div>
+
+</section> 
 
 </div>
 </section> <!-- Base specs -->
@@ -2120,7 +2186,8 @@
 
 <!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130930/">Candidate Recommendation Draft</a></em></blockquote> wah -->
 <ul>
-    <li>2013-10-25 - Resolve ACTION-105 ACTION-105: Update spec to reflect 9/30 resolution moving Paging links to HTTP headers (JA)</li>
+    <li>2013-11-11 - Resolve ACTION-113 Update spec to reflect 11/04 resolution to remove 303 and have client use first/next links to detect paging (JA)</li>
+    <li>2013-10-25 - Resolve ACTION-105 Update spec to reflect 9/30 resolution moving Paging links to HTTP headers (JA)</li>
     <li>2013-10-25 - Resolve ACTION-110 Update spec to reflect 10/21 resolution for normative changes to align vanilla/chocolate (JA)</li>
     <li>2013-10-22 - Resolve ACTION-109 Update spec to reflect 10/21 resolution for ignoring triples on PUT (JA)</li>
     <li>2013-10-22 - Resolve ACTION-107 Update spec to reflect 10/07 resolution on 5.6.2 LDPC deletion (JA)</li>