--- a/ldp-paging.html Tue Jul 08 13:02:37 2014 -0400
+++ b/ldp-paging.html Tue Jul 08 16:39:11 2014 -0400
@@ -12,7 +12,7 @@
but it doesn't exist in rules or vocabulary doc, oversight?
TODO: Mine Jim des Riv May 21 email for more content
TODO: Example 11 is missing ldp:contains, true? Omit due to GET on page resource, should make it more clear.
- TODO: Paging intro: add 3rd example showing header link age amongst pages and (HEAD on) the base resource.
+ TODO: Paging intro: add 3rd example showing header linkage amongst pages and (HEAD on) the base resource.
Maybe also insert HEAD on base as new first example instead of relying on text alone.
TODO: Missing namespace definition clause?
-->
@@ -266,13 +266,31 @@
<section class="informative" id="intro">
<!-- TODO: Move bulk of paging intro here - it's not rocket science -->
<h1>Introduction</h1>
- <p>This specification provides a widely re-usable pattern to deal with large resources.
- Depending on the client's and server’s capabilities, a GET request on a <a title="Paged resource">resource</a> can
- be redirected to a <a title="In-Sequence Page resource">subset of the resource (one page)</a>, that provides access to subsequent pages
- (see <a href="#ldpr-Paging" class="sectionRef"></a>).
+ <p>
+ This specification provides a widely re-usable pattern to make the state of a large <a title="Paged resource">paged HTTP resource</a>
+ available as a list of smaller subset resources (<a title="In-sequence page resource">pages</a>) whose
+ representations are less burdensome for servers to form.
+ <a title="Paged resource">Paged resources</a> must be LDP Resources (LDPRs) [[!LDP]].
+ Any LDPR can be paged, but certain aspects of paging like ordering are only well-defined for
+ particular sub-classes of LDPRs, like
+ LDP-RSs or LDPCs.
</p>
- <p>For context and background, it could be useful to read <a href="#bib-LDP-UCR">Linked Data Platform Use Case and Requirements</a> [[LDP-UCR]]
- and <a href="#base-specs" class="sectionRef"></a>.</p>
+ <p>
+ When a client attempts to retrieve a <a>paged resource</a>, the server either redirects the client to
+ a "first page" <a title="In-sequence page resource">resource</a> or provides the
+ representation of the "first page" <a title="In-sequence page resource">resource</a> in its response,
+ depending on the client's request preferences. <a title="LDP Paging client">Paging-aware clients</a>
+ can save the latency of making a second request to retrieve the first page when the server supports this,
+ in addition to knowing how to combine pages.
+ In either case, the response containing the first page's representation
+ includes a link to another page in the sequence, as do all other non-terminal pages.
+ LDP Paging defines a mechanism by which clients can learn that the <a>paged resource</a> has been changed
+ so that they can, for example, abandon a page traversal as early as possible.
+ </p>
+ <p>
+ For context and background, it could be useful to read <a href="#bib-LDP-UCR">Linked Data Platform Use Case and Requirements</a> [[LDP-UCR]]
+ and <a href="#base-specs" class="sectionRef"></a>.
+ </p>
</section>
<section id="terms">
@@ -671,23 +689,33 @@
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.
- The client
- retrieves <code>http://example.org/customer-relations</code>, and
- the server responds with <a href="#atrisk-2NN">status code <code>2NN Contents of Related</code></a>,
+ </p>
+
+<em>Request</em>
+<pre class="example">GET /customer-relations HTTP/1.1
+Host: example.org
+Accept: text/turtle
+</pre>
+ <p>
+ The server responds with <a href="#atrisk-2NN">status code <code>2NN Contents of Related</code></a>,
a <code>Location: http://example.org/customer-relations?page1</code> HTTP response header
identifying the first page as the resource whose representation is enclosed in the response,
and the following representation:
</p>
-<!-- TODO: HTTP envelope to all requests/responses, and show requests where they're omitted today -->
-<pre class="example" id="ldpc-ex-page1"># The following is the representation of
-# http://example.org/customer-relations?page1
-# Requests on the URI will result in responses that include the following HTTP headers
-# Link: <http://www.w3.org/ns/ldp#Page>; rel='type'
-# Link: <http://example.org/customer-relations?p=2>; rel='next'
-# Link: <http://example.org/customer-relations>; rel='canonical'; etag="customer-relations-v1"
-# This Link header is how clients discover the URI of the next page in sequence,
-# and that the resource supports paging.
+<em>Response:</em>
+<pre class="example" id="ldpc-ex-page1">
+HTTP/1.1 2NN Contents of Related
+Content-Type: text/turtle
+ETag: "_87e52ce291112"
+Location: <http://example.org/customer-relations?page1>
+Link: <http://www.w3.org/ns/ldp#Resource>; rel="type",
+ <http://www.w3.org/ns/ldp#Page>; rel="type"
+Link: <http://example.org/customer-relations?p=2>; rel='next'
+Link: <http://example.org/customer-relations>; rel='canonical'; etag="customer-relations-v1"
+Allow: GET,OPTIONS,HEAD
+Transfer-Encoding: chunked
+
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
@@ -723,16 +751,29 @@
</p>
<p>
The following example is the result of retrieving
- the next page;
- the server responds with status code <code>200 OK</code> and the following representation:
+ the next page:
</p>
-<pre class="example" id="ldpc-ex-page2"># The following is the representation of
-# http://example.org/customer-relations?p=2
-#
-# Requests on the URI will result in responses that include the following HTTP headers
-# Link: <http://www.w3.org/ns/ldp#Page>; rel='type'
-# Link: <http://example.org/customer-relations>; rel='canonical'; etag="customer-relations-v1"
+<em>Request</em>
+<pre class="example">GET /customer-relations?p=2 HTTP/1.1
+Host: example.org
+Accept: text/turtle
+</pre>
+ <p>
+ The server responds with status code <code>200 OK</code> and the following representation:
+ </p>
+
+<em>Response:</em>
+<pre class="example" id="ldpc-ex-page2">
+HTTP/1.1 200 OK
+Content-Type: text/turtle
+ETag: "8_7e52ce291112"
+Link: <http://www.w3.org/ns/ldp#Resource>; rel="type",
+ <http://www.w3.org/ns/ldp#Page>; rel="type"
+Link: <http://example.org/customer-relations>; rel='canonical'; etag="customer-relations-v1"
+Allow: GET,OPTIONS,HEAD
+Transfer-Encoding: chunked
+
#
# There is no "next" Link in the server's response, so this is the final page.
#
@@ -1118,7 +1159,25 @@
<p>Here is an example asset container described in [[LDP]] section 5.1,
with the ordering of the assets asserted:</p>
+<em>Request</em>
+<pre class="example">GET /netWorth/nw1/assetContainer/ HTTP/1.1
+Host: example.org
+Accept: text/turtle
+</pre>
+ <p>
+ The server responds with status code <code>200 OK</code>,
+ and the following representation:
+ </p>
+
+<em>Response:</em>
<pre class="example" id="ldpc-ex-ordering">
+HTTP/1.1 200 OK
+Content-Type: text/turtle
+ETag: "_87e52ff291112"
+Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
+Allow: GET,OPTIONS,HEAD
+Transfer-Encoding: chunked
+
# The following is the ordered representation of
# http://example.org/netWorth/nw1/assetContainer/
<!-- @base is here only so it's easier to paste into validators for checking -->