Issue-65 remove firstPage
authorJohn Arwe
Tue, 21 May 2013 08:55:30 -0400
changeset 114 1629ff899e0e
parent 113 6fd1ba20242d
child 115 c8f6c689d373
Issue-65 remove firstPage
ldp.html
--- a/ldp.html	Fri May 17 16:14:22 2013 -0400
+++ b/ldp.html	Tue May 21 08:55:30 2013 -0400
@@ -481,6 +481,10 @@
 
 <section>
 <h2 id="ldpr-HTTP_HEAD">HTTP HEAD</h2>
+	<p>Note that certain LDP mechanisms, such as paging, rely on HTTP headers, and HTTP generally requires that
+		HEAD responses include the same headers as GET responses.  
+		Thus, implementers should also carefully read the
+		<a href="#ldpr-HTTP_GET">GET section</a>.</p>
 	<div id="ldpr-4_6_1" class="rule">4.6.1 LDPR servers MUST support the HTTP HEAD method.</div>
 	<div id="ldpr-4_6_2" class="rule">4.6.2 LDPR servers MUST indicate their support for HTTP Methods by
 		responding to a HTTP HEAD request on the LDPR’s URL with the HTTP
@@ -780,9 +784,10 @@
 	<p>
 		To address this problem, LDPCs should support a technique called Paging.  Paging can be achieved with a
 		simple RDF pattern. For each container resource, <code>&lt;containerURL&gt;</code>, we define a new
-		resource <code>&lt;containerURL&gt;?firstPage</code>.
-		The triples in the representation of <code>&lt;containerURL&gt;?firstPage</code>
-		are a subset of the triples in <code>&lt;containerURL&gt;</code>
+		'first page' resource.  In this example, its URL will be <code>&lt;containerURL&gt;?firstPage</code>,
+		but servers are free to construct the URL as they see fit.
+		The triples in the representation of the each page
+		are a subset of the triples in the container
 		- same subject, predicate and object.
 	</p>
 	<p>LDPC servers may respond to requests for a
@@ -791,7 +796,12 @@
 		resource.</p>
 	<p>
 		Continuing on from the member information from the JohnZSmith net
-		worth example, we’ll split the response across two pages.  The client
+		worth example, we’ll split the response across two pages.  
+		To find the URL of the first page, the client makes a <code>HEAD</code> request
+		to the container's URL, 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/netWorth/nw1/assetContainer/?firstPage</code>:
 	</p>
 <pre class="example"># The following is the representation of
@@ -1041,36 +1051,38 @@
 	Non-member-properties and Hypermedia as the Engine of Application State (HATEOAS) Compliance
 	</div>
 	
-	<div id="ldpc-5_3_3" class="rule">5.3.3 An LDPC server that does not support a request to retrieve the first
+	<div id="ldpc-5_3_3" class="rule">5.3.3 Empty after resolution of Issue-65, 
+		left here for now to avoid renumbering all that follows.
+		Used to be <blockquote><strike>
+		An LDPC server that does not support a request to retrieve the first
 		page resource representation from a known LDPC whose URL is “<code>&lt;containerURL&gt;</code>” by using
 		the Request-URI “<code>&lt;containerURL&gt;?firstPage</code>”, MUST return a HTTP status code 404 (Not
 		Found).
 		An LDPC server that supports that request using a different Request-URI than “<code>&lt;containerURL&gt;?firstPage</code>”,
 		MUST return a HTTP Redirection 3xx status code such as 301 (Moved Permanently) or 302 (Found).
+		</strike></blockquote>
 	</div>
 	
-	<div class="ldp-issue">
-	<div class="ldp-issue-title"><a href="http://www.w3.org/2012/ldp/track/issues/65">ISSUE-65</a></div>
-	FirstPage and Hypermedia as the Engine of Application State (HATEOAS) Compliance
-	</div>
-	
-	<div id="ldpc-5_3_4" class="rule">5.3.4 LDPC servers SHOULD support requests for splitting large LDPCs into
-		pages indicated by a client supplying the token “<code>firstPage</code>”
-		on the query component of the LDPC URL. For example, if there is a LDPC
-		URL <code>&lt;containerURL&gt;</code>, the URL to request
-		the first page would be <code>&lt;containerURL&gt;?firstPage</code>.
+	<div id="ldpc-5_3_4" class="rule">5.3.4 LDPC servers SHOULD allow clients to retrieve large LDPCs in
+		pages. In responses to <code>GET</code> requests with an LDPC as the Request-URI, 
+		LDPC servers that support paging SHOULD provide an HTTP <code>Link</code>
+		header whose target URI is the first page resource, and whose link relation type is <code>first</code> [[!RFC5988]]. 
+		This is the mechanism by which clients discover the URL of the first page.  If no such <code>Link</code>
+		header is present, then conservative clients will assume that the LDPC does not support paging.
+		For example, if there is a LDPC with URL <code>&lt;containerURL&gt;</code> that supports paging and whose
+		first page URL is <code>&lt;containerURL&gt;?theFirstPage</code>, then the corresponding link header
+		would be <code>Link: &lt;?theFirstPage&gt;;rel="first"</code>
 		The representation for any page, including the first, will include
 		the URL for the next page. See section <a href="#ldpc-paging">5.1.3 Paging</a> for additional details.
 	</div>
-	<div id="ldpc-5_3_5" class="rule">5.3.5 LDPC servers MAY split the response representation of a LDPC regardless
-		of what the client requested (such as when a client omits a “<code>firstPage</code>”
-		query component of a request URL). This is also known as
+	<div id="ldpc-5_3_5" class="rule">5.3.5 LDPC servers MAY split the response representation of any LDPC. 
+		This is known as
 		server-initiated paging. See section  <a href="#ldpc-paging">5.1.3 Paging</a> for
 		additional details.
 	</div>
 	<div id="ldpc-5_3_5_1" class="rule">5.3.5.1 LDPC servers that initiate paging SHOULD respond to requests for a LDPC
-		by redirecting the client to the page resource – using a 303 “See
-		Other” redirect to the actual URL for the page resource.
+		by redirecting the client to the first page resource using a <code>303 See
+		Other</code> response with an HTTP <code>Location</code> header providing the first page resource URL.
 	</div>
 	<div id="ldpc-5_3_6" class="rule">5.3.6 LDPC servers that support paging MUST include in the page
 		representation a representation for the LDPC, such that:
@@ -1241,6 +1253,10 @@
 <h2 id="ldpc-HTTP_HEAD">HTTP HEAD</h2>
 	<p>There are no additional requirements on HTTP
 		HEAD.</p>
+	<p>Note that certain LDP mechanisms, such as paging, rely on HTTP headers, and HTTP generally requires that
+		HEAD responses include the same headers as GET responses.  
+		Thus, implementers supporting HEAD should also carefully read the
+		<a href="#ldpc-HTTP_GET">GET section</a>.</p>
 </section>
 
 <section>