--- a/ldp-paging.html Tue Jul 08 16:39:11 2014 -0400
+++ b/ldp-paging.html Wed Jul 09 11:18:31 2014 -0400
@@ -14,7 +14,7 @@
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 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?
+ DONE: Missing namespace definition clause?
-->
<html>
<head>
@@ -289,7 +289,7 @@
</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>.
+ and <a href="#base-specs" class="sectionRef"></a>. A detailed example is provided in <a href="#ldpp-ex-mx" class="sectionRef"></a>.
</p>
</section>
@@ -382,6 +382,7 @@
<a title="In-sequence page resource"><em>individual page resources</em></a>,
in cases where both are mentioned in
close proximity.
+ </p>
<p></p></dd>
<dt><dfn>first page link</dfn></dt>
@@ -445,6 +446,7 @@
<section id="conventions">
<h2>Conventions Used in This Document</h2>
+ <p>The namespace for LDP Paging is <code>http://www.w3.org/ns/ldp#</code>.</p>
<p>Sample resource representations are provided in <code>text/turtle</code>
format [[turtle]].</p>
<p>Commonly used namespace prefixes:</p>
@@ -462,21 +464,26 @@
<p>The status of the sections of Linked Data Platform Paging 1.0 (this document) is as follows:</p>
<ul>
- <li>1. Introduction: <b>non-normative</b></li>
- <li>2. Terminology</li>
+ <li><a href="#intro" class="sectionRef"></a>: <b>non-normative</b></li>
+ <li><a href="#terms" class="sectionRef"></a></li>
<ul>
- <li>2.1 Terms re-used from the Linked Data Platform: <b>non-normative</b></li>
- <li>2.2 Terms normatively defined by this specification: <b>normative</b></li>
- <li>2.3 Conventions Used in This Document: <b>normative</b></li>
+ <li><a href="#terms-from-ldp" class="sectionRef"></a>: <b>non-normative</b></li>
+ <li><a href="#terms-from-paging" class="sectionRef"></a>: <b>normative</b></li>
+ <li><a href="#conventions" class="sectionRef"></a>: <b>normative</b></li>
</ul>
- <li>3. Conformance: <b>normative</b></li>
- <li>4. Linked Data Platform Paging Clients: <b>normative</b></li>
- <li>5. Linked Data Platform Resources: <b>normative</b></li>
- <li>6. Linked Data Platform Containers: <b>normative</b></li>
- <li>7. Notable information from normative references: <b>non-normative</b></li>
- <li>A. Acknowledgements: <b>non-normative</b></li>
- <li>B.1 Normative references: <b>normative</b></li>
- <li>B.2 Non-normative references: <b>non-normative</b></li>
+ <li><a href="#conformance" class="sectionRef"></a>: <b>normative</b></li>
+ <li><a href="#ldpp-ex-mx" class="sectionRef"></a>: <b>non-normative</b></li>
+ <li><a href="#ldppclient" class="sectionRef"></a>: <b>normative</b></li>
+ <li><a href="#ldpr" class="sectionRef"></a>: <b>normative</b></li>
+ <li><a href="#ldpc" class="sectionRef"></a>: <b>normative</b></li>
+ <li><a href="#base-specs" class="sectionRef"></a>: <b>non-normative</b></li>
+ <!-- TODO: figure out why next 2 do not show up in TOC or get
+ resolved as sectionrefs ... probably an unbalanced tag
+ somewhere -->
+ <li><a href="#security" class="sectionRef"></a>: <b>non-normative</b></li>
+ <li><a href="#acks" class="sectionRef"></a>: <b>non-normative</b></li>
+ <li><a href="#normative-references" class="sectionRef"></a>: <b>normative</b></li>
+ <li><a href="#informative-references" class="sectionRef"></a>: <b>non-normative</b></li>
</ul>
<p>A conforming <b><dfn>LDP Paging client</dfn></b> is a conforming LDP client [[!LDP]] that follows the rules defined by LDP Paging.
@@ -485,12 +492,531 @@
<p>A conforming <b><dfn>LDP Paging server</dfn></b> is a conforming LDP server [[!LDP]] that follows the rules defined by LDP Paging.</p>
</section>
+<section class="informative" id="ldpp-ex-mx">
+<h1>Example paging message exchanges</h1>
+
+ <p>
+ Example Co.'s customer
+ relationship data is identified by the URI <code>http://example.org/customer-relations</code>,
+ and is retrievable using the same URI.
+ </p>
+
+<section id="ldpp-ex-no-paging">
+<h2>Traditional flow without paging</h2>
+
+ <p>
+ A standard HTTP client that knows nothing about LDP paging obtains a representation of the
+ resource in the usual way.
+ </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 status code <code>200 OK</code> and the following representation:
+ </p>
+
+<em>Response:</em>
+<pre class="example" id="ldpp-ex-no-paging-resp">
+HTTP/1.1 200 OK
+Content-Type: text/turtle
+ETag: "_87e52ce291112"
+Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
+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/>.
+@prefix ldp: <http://www.w3.org/ns/ldp#>.
+@prefix o: <http://example.org/ontology/>.
+@base <http://example.org/customer-relations>.
+
+<>
+ a o:CustomerRelations;
+ dcterms:title "The customer information for Example Co.";
+ o:client <#JohnZSmith>, <#BettyASmith>, <#JoanRSmith>,
+ <#GlenWSmith>, <#AlfredESmith>.
+
+<#JohnZSmith>
+ a foaf:Person;
+ o:status o:ActiveCustomer;
+ foaf:name "John Z. Smith".
+
+<#BettyASmith>
+ a foaf:Person;
+ o:status o:PreviousCustomer;
+ foaf:name "Betty A. Smith".
+
+ <#JoanRSmith>
+ a foaf:Person;
+ o:status o:PotentialCustomer;
+ foaf:name "Joan R. Smith".
+
+<#GlenWSmith>
+ a foaf:Person;
+ o:status o:ActiveCustomer, o:GoldCustomer;
+ foaf:name "Glen W. Smith".
+
+<#AlfredESmith>
+ a foaf:Person;
+ o:status o:ActiveCustomer, o:BronzeCustomer;
+ foaf:name "Alfred E. Smith".
+</pre>
+
+ <p>
+ As long as the resource being retrieved is small enough that the server can form its
+ representation without running into implementation limits on memory etc., and as long
+ as the client is likewise able to consume these representations, this pattern works
+ fine. Indeed, it's by far the most common pattern on the Web.
+ </p>
+ <p>
+ At the point where server and/or client constraints or consumption preferences come into play, however,
+ something else is needed. LDP Paging addresses this need by giving clients and
+ servers the ability to partition representations into smaller pieces, transfer
+ as many as the client needs (potentially a small subset of the resource's full
+ state), and allows the client to reassemble the pieces (or not) as it prefers.
+ One sees this pattern in contexts such as search page results, as one common
+ example.
+ </p>
+
+</section>
+
+<section id="ldpp-ex-paging-303">
+<h2>Simple paging flow using redirects</h2>
+
+ <p>
+ The simplest possible solution would be to redefine the meaning of the existing
+ URI <code>http://example.org/customer-relations</code> from "all customer relations information"
+ to "the first chunk of all customer relations information". This would require changes to
+ any existing clients whose code was built using the original definition however, so it's
+ more likely that Example Co. would mint a new URI for "the first chunk", define a way to
+ find subsequent chunks, and have clients use this new protocol.
+ </p>
+ <p>
+ The new protocol does not solve the problem of migrating existing clients from the old
+ "all" to the new "first chunk" semantic; neither would a <code>303 See Other</code> redirect
+ from the old to the new URI, given the widespread historical client practice of automatically
+ following <code>303</code> redirects and treating the redirected-to resource as equivalent
+ to the original. The safe route is to have clients explicitly tell the server that they
+ are capable of handling the "first chunk" semantic on the redirected-to URI; this is what
+ LDP Paging does.
+ </p>
+ <p>
+ A client aware of LDP paging obtains a representation of the
+ resource in the usual way, and also signals its ability to handle redirection to a first-page resource:
+ </p>
+
+<em>Request</em>
+<pre class="example">GET /customer-relations HTTP/1.1
+Host: example.org
+Accept: text/turtle
+Prefer: return=representation; page-size="500 rdf-triples"
+</pre>
+
+ <p>
+ The server responds with <code>303 See Other</code>, and
+ a <code>Location: http://example.org/customer-relations?page1</code> HTTP response header
+ identifying the target resource.
+ </p>
+
+<em>Response:</em>
+<pre class="example" id="ldpp-ex-paging-303-resp1">
+HTTP/1.1 303 See Other
+Location: <http://example.org/customer-relations?page1>
+Transfer-Encoding: chunked
+</pre>
+
+ <p>
+ At this point the client does not know if the target
+ resource is "all" or "the first chunk"; it has to retrieve the resource to know.
+ </p>
+
+<em>Request</em>
+<pre class="example">GET /customer-relations?page1 HTTP/1.1
+Host: example.org
+Accept: text/turtle
+Prefer: return=representation; page-size="500 rdf-triples"
+</pre>
+ <p>
+ The server responds with status code <code>200 OK</code>,
+ and the following representation:
+ </p>
+
+<em>Response:</em>
+<pre class="example" id="ldpp-ex-paging-303-resp2">
+HTTP/1.1 200 OK
+Content-Type: text/turtle
+ETag: "_87e52ce291112"
+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/>.
+@prefix ldp: <http://www.w3.org/ns/ldp#>.
+@prefix o: <http://example.org/ontology/>.
+@base <http://example.org/customer-relations>.
+
+<>
+ a o:CustomerRelations;
+ dcterms:title "The customer information for Example Co.";
+ o:client <#JohnZSmith>, <#BettyASmith>, <#JoanRSmith>.
+
+<#JohnZSmith>
+ a foaf:Person;
+ o:status o:ActiveCustomer;
+ foaf:name "John Z. Smith".
+<#BettyASmith>
+ a foaf:Person;
+ o:status o:PreviousCustomer;
+ foaf:name "Betty A. Smith".
+ <#JoanRSmith>
+ a foaf:Person;
+ o:status o:PotentialCustomer;
+ foaf:name "Joan R. Smith".
+</pre>
+
+ <p>
+ From this response, 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 specification, with the client's <code>page-size</code> preference as one
+ input; the simplest method is to make the server's page size equal
+ to the client's preference. In this example, the server chooses a smaller value so
+ there is a second page.
+ </p>
+ <ul>
+ <li>
+ The <code>Link: <http://example.org/customer-relations>; rel='canonical'</code>
+ response header tells the client which resource <code><http://example.org/customer-relations?page1></code>
+ is a page of. The <code>etag="customer-relations-v1"</code> parameter value gives the client a way to know,
+ during its page traversal, whether or not the canonical <a>paged resource</a> has changed; not all
+ clients will use this information, but it is there for those that can make use of it.
+ </li>
+ <li>
+ The <code>Link: <http://www.w3.org/ns/ldp#Page>; rel="type"</code>
+ response header tells the client that this is one <a>in-sequence page resource</a>, and therefore it
+ needs to examine the other response headers to see if more data existed in the
+ canonical <a>paged resource</a> when the response
+ was generated by the server.
+ </li>
+ <li>
+ The <code>Link: <http://example.org/customer-relations?p=2>; rel='next'</code>
+ response header tells the client that at least one more <a>in-sequence page resource</a> exists,
+ and how to retrieve its representation. The next page link's target URI is
+ defined by the server and is not constrained by this specification.
+ </li>
+ </ul>
+ <p>
+ The following example shows the message exchange for retrieving
+ the next page:
+ </p>
+
+<em>Request</em>
+<pre class="example">GET /customer-relations?p=2 HTTP/1.1
+Host: example.org
+Accept: text/turtle
+Prefer: return=representation; page-size="500 rdf-triples"
+</pre>
+ <p>
+ The server responds with status code <code>200 OK</code> and the following representation:
+ </p>
+
+<em>Response:</em>
+<pre class="example" id="ldpp-ex-paging-303-resp3">
+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
+
+@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/>.
+@prefix ldp: <http://www.w3.org/ns/ldp#>.
+@prefix o: <http://example.org/ontology/>.
+@base <http://example.org/customer-relations>.
+
+<>
+ o:client <#GlenWSmith>, <#AlfredESmith>.
+
+<#GlenWSmith>
+ a foaf:Person;
+ o:status o:ActiveCustomer, o:GoldCustomer;
+ foaf:name "Glen W. Smith".
+
+<#AlfredESmith>
+ a foaf:Person;
+ o:status o:ActiveCustomer, o:BronzeCustomer;
+ foaf:name "Alfred E. Smith".
+ </pre>
+
+ <p>
+ In this example, there are only two customers provided in the
+ second page.
+ </p>
+ <!-- TODO: show it both ways; if a competing change hit the container, or not -->
+ <ul>
+ <li>
+ The <code>Link: <http://www.w3.org/ns/ldp#Page>; rel="type"</code>
+ response header tells the client that this is one <a>in-sequence page resource</a>, and therefore it
+ needs to examine the other response headers to see if more data existed in the
+ canonical <a>paged resource</a> when the response
+ was generated by the server.
+ </li>
+ <li>
+ The absence of a <code>Link: <http://example.org/customer-relations?p=2>; rel='next'</code>
+ response header tells the client that no more <a>in-sequence page resource</a>s existed in this <a>paged resource</a>
+ at the time the response was generated; repeating the request might result in a representation with links to more pages,
+ if other processes are updating the customer relations data.
+ </li>
+ <li>
+ Since the <code>etag="customer-relations-v1"</code> parameter value of the canonical <a>paged resource</a>
+ did not change across the client's process of retrieving the entire page sequence, it is assured that
+ the merged response representations are equivalent to what it would have received had the server
+ provided the entire representation of the <a>paged resource</a> in a single <code>200 OK</code> response.
+ The client has <em>no assurance</em> that the current state of the <a>paged resource</a> remains unchanged
+ since the final page's representation was generated. For example, after the server constructs the final page representation, another
+ actor could delete <code>client#BettyASmith</code> from the server.
+ </li>
+ </ul>
+
+</section>
+
+<section id="ldpp-ex-paging-2nn">
+<h2>Optimized paging flow</h2>
+
+ <p>
+ It is inconvenient that the <a href="#ldpp-ex-paging-303"><code>303 See Other</code> approach</a>
+ requires three message exchanges to transfer two representations. Fortunately, it is possible to
+ remove the extra message exchange, saving the latency and the server plus network overhead of
+ servicing the <code>303</code> messages.
+ </p>
+ <p>
+ If a client signals that it is capable of understanding the HTTP
+ <a href="#atrisk-2NN">status code <code>2NN Contents of Related</code></a>, then the server can
+ respond with <code>2NN Contents of Related</code> instead of <code>303 See Other</code> on the
+ initial retrieval request, and it can also enclose the representation of the first page in the
+ corresponding response.
+ </p>
+
+<em>Request</em>
+<pre class="example">GET /customer-relations HTTP/1.1
+Host: example.org
+Accept: text/turtle
+Prefer: return=representation; page-size="500 rdf-triples"
+Prefer: contents-of-related
+</pre>
+
+ <p>
+ The server responds with <a href="#atrisk-2NN">status code <code>2NN Contents of Related</code></a>,
+ and the representation given below along with its associated response and representation metadata headers.
+ </p>
+ <p>
+ As was true in the <a href="#ldpp-ex-paging-303"></a><code>303 See Other</code> approach</a>,
+ the server includes
+ 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.
+ </p>
+
+<em>Response:</em>
+<pre class="example" id="ldpp-ex-paging-2nn-resp1">
+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/>.
+@prefix ldp: <http://www.w3.org/ns/ldp#>.
+@prefix o: <http://example.org/ontology/>.
+@base <http://example.org/customer-relations>.
+
+<>
+ a o:CustomerRelations;
+ dcterms:title "The customer information for Example Co.";
+ o:client <#JohnZSmith>, <#BettyASmith>, <#JoanRSmith>.
+
+<#JohnZSmith>
+ a foaf:Person;
+ o:status o:ActiveCustomer;
+ foaf:name "John Z. Smith".
+<#BettyASmith>
+ a foaf:Person;
+ o:status o:PreviousCustomer;
+ foaf:name "Betty A. Smith".
+ <#JoanRSmith>
+ a foaf:Person;
+ o:status o:PotentialCustomer;
+ foaf:name "Joan R. Smith".
+</pre>
+
+ <p>
+ From this response, the client knows that it received the representation of an
+ <a>in-sequence page resource</a> instead of the <a>paged resource</a>,
+ that at least one more page exists, and where to find the next page.
+ The server determines the size of the pages using application-specific methods not defined
+ within this specification, with the client's <code>page-size</code> preference as one
+ input; the simplest method is to make the server's page size equal
+ to the client's preference. In this example, the server chooses a smaller value so
+ there is a second page.
+ </p>
+ <ul>
+ <li>
+ The <code>2NN Contents of Related</code> status code
+ tells the client that the response contains a representation of some resource <em>other than</em>
+ the one identified by its effective request URI.
+ </li>
+ <li>
+ The <code>Location: <http://example.org/customer-relations?page1></code>
+ response header tells the client the identifier of the response representation's resource.
+ In the context of a response with a <code>2NN Contents of Related</code> status code,
+ it tells the client the "related" resource's identifier.
+ </li>
+ <li>
+ The <code>Link: <http://example.org/customer-relations>; rel='canonical'</code>
+ response header tells the client which resource <code><http://example.org/customer-relations?page1></code>
+ is a page of, providing more specificity about the nature of the relationship between the
+ resource identified by the effective
+ request URI and the resource identified in the <code>Location</code> header.
+ The <code>etag="customer-relations-v1"</code> parameter value gives the client a way to know,
+ during its page traversal, whether or not the canonical <a>paged resource</a> has changed; not all
+ clients will use this information, but it is there for those that can make use of it.
+ </li>
+ <li>
+ The <code>Link: <http://www.w3.org/ns/ldp#Page>; rel="type"</code>
+ response header tells the client that this is one <a>in-sequence page resource</a>, and therefore it
+ needs to examine the other response headers to see if more data existed in the
+ canonical <a>paged resource</a> when the response
+ was generated by the server.
+ </li>
+ <li>
+ The <code>Link: <http://example.org/customer-relations?p=2>; rel='next'</code>
+ response header tells the client that at least one more <a>in-sequence page resource</a> exists,
+ and how to retrieve its representation. The next page link's target URI is
+ defined by the server and is not constrained by this specification.
+ </li>
+ </ul>
+ <p>
+ The following example shows the message exchange for retrieving
+ the next page:
+ </p>
+
+<em>Request</em>
+<pre class="example">GET /customer-relations?p=2 HTTP/1.1
+Host: example.org
+Accept: text/turtle
+Prefer: return=representation; page-size="500 rdf-triples"
+Prefer: contents-of-related
+</pre>
+ <p>
+ The server responds with status code <code>200 OK</code> and the following representation:
+ </p>
+
+<em>Response:</em>
+<pre class="example" id="ldpp-ex-paging-2nn-resp2">
+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.
+#
+@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/>.
+@prefix ldp: <http://www.w3.org/ns/ldp#>.
+@prefix o: <http://example.org/ontology/>.
+@base <http://example.org/customer-relations>.
+
+<>
+ o:client <#GlenWSmith>, <#AlfredESmith>.
+
+<#GlenWSmith>
+ a foaf:Person;
+ o:status o:ActiveCustomer, o:GoldCustomer;
+ foaf:name "Glen W. Smith".
+
+<#AlfredESmith>
+ a foaf:Person;
+ o:status o:ActiveCustomer, o:BronzeCustomer;
+ foaf:name "Alfred E. Smith".
+ </pre>
+
+ <p>
+ In this example, there are only two customers provided in the
+ second page.
+ </p>
+ <ul>
+ <li>
+ The <code>Link: <http://www.w3.org/ns/ldp#Page>; rel="type"</code>
+ response header tells the client that this is one <a>in-sequence page resource</a>, and therefore it
+ needs to examine the other response headers to see if more data existed in the
+ canonical <a>paged resource</a> when the response
+ was generated by the server.
+ </li>
+ <li>
+ The absence of a <code>Link: <http://example.org/customer-relations?p=2>; rel='next'</code>
+ response header tells the client that no more <a>in-sequence page resource</a>s existed in this <a>paged resource</a>
+ at the time the response was generated; repeating the request might result in a representation with links to more pages,
+ if other processes are updating the customer relations data.
+ </li>
+ <li>
+ Since the <code>etag="customer-relations-v1"</code> parameter value of the canonical <a>paged resource</a>
+ did not change across the client's process of retrieving the entire page sequence, it is assured that
+ the merged response representations are equivalent to what it would have received had the server
+ provided the entire representation of the <a>paged resource</a> in a single <code>200 OK</code> response.
+ The client has <em>no assurance</em> that the current state of the <a>paged resource</a> remains unchanged
+ since the final page's representation was generated. For example, after the server constructs the final page representation, another
+ actor could delete <code>client#BettyASmith</code> from the server.
+ </li>
+ </ul>
+
+</section>
+
+</section> <!-- Example message exchanges -->
+
<section id="ldppclient">
<h1>Linked Data Platform Paging Clients</h1>
<p>All of the following are conformance rules for <a title="LDP Paging client">LDP Paging Clients</a>.
</p>
<section><h2>General</h2>
+ <section id="ldpp-client-advertise"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST
+ <a href="#prefer-rules">advertise their ability to support LDP Paging</a> on all retrieval requests that normally result in
+ a response containing a representation.
+ </h2>
+ <div class="ldp-issue-pending" id="what-the-pagesize-required"><p class="ldp-issue-title">For Discussion</p>
+ <p>
+ Given that servers Must Not initiate paging unless the client acks that it understands LDP paging,
+ e.g. by sending a Prefer: pagesize header, do we want to add a Must on clients to send that header?
+ Some support for doing so on the mailing list week of 7 July 2014 resulted in <a href="#ldpp-client-advertise" class="sectionRef">this strawman</a>.
+ </p>
+ </div>
+ </section>
+
<section id="ldpp-client-traversal"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST
be capable of at least one of <a>forward traversal</a> and/or <a>backward traversal</a>.
</h2>
@@ -533,7 +1059,8 @@
<section id="ldpp-hints-summary">
<h3>Summary</h3>
- <p>This specification introduces new ...
+ <p>
+ This specification introduces new ...
<!-- TODO: fill in summary -->
<!--
parameters on the HTTP <code>Prefer</code> request header's
@@ -559,8 +1086,8 @@
<code>Preference-Applied</code> response header when the client cannot otherwise determine the server's
behavior with respect to honoring hints from the response content.
<a href="#prefer-examples">Examples</a> illustrates some cases where the header is unnecessary.
+ -->
</p>
- -->
</section> <!-- Prefer summary -->
@@ -568,7 +1095,11 @@
<h3>Specification</h3>
<section id="ldpp-hints-page-size"><h2 class="normal">
- The <code>page-size</code> hint defines the client's maximum desired size for a response representation.
+ The <code>page-size</code> hint
+ <ul>
+ <li>signals the client's support for LDP Paging to the request server</li>
+ <li>defines the client's maximum desired size for a response representation</li>
+ </ul>
A client communicates its hint to the server by adding a
HTTP preference request header with
<code>return=representation</code> that includes a
@@ -591,7 +1122,8 @@
preference parameter; LDP Paging assigns a meaning to the value only when it is a quoted string.
<a title="LDP Paging server">LDP Paging servers</a> MAY
ignore a page size of zero, or unrecognized <code>units</code>,
- and process the request as if the hint was absent.
+ and process the request as if no maximum desired size was specified; in the latter case the server
+ can select whatever page size it deems appropriate.
</p>
</blockquote>
</section>
@@ -620,6 +1152,13 @@
<section class="informative" id="ldpr-informative">
<h2>Introduction</h2>
+ <div class="ldp-issue-closed"><p class="ldp-issue-title">Editorial note</p>
+ <p>
+ There is more duplication between this content (its original home) and other sections
+ (<a href="#intro" class="sectionRef"></a>, <a href="#ldpp-ex-mx" class="sectionRef"></a>) than we'd prefer.
+ It's on-going work to reduce the duplication.
+ </p>
+ </div>
<p>
Some LDPRs are too large to reasonably transmit a representation in a
single HTTP response.
@@ -665,6 +1204,13 @@
<section class="informative" id="ldpr-PagingIntro">
<h3>Introduction</h3>
+ <div class="ldp-issue-closed"><p class="ldp-issue-title">Editorial note</p>
+ <p>
+ There is more duplication between this content (its original home) and other sections
+ (<a href="#intro" class="sectionRef"></a>, <a href="#ldpp-ex-mx" class="sectionRef"></a>) than we'd prefer.
+ It's on-going work to reduce the duplication.
+ </p>
+ </div>
<p>
<a title="LDP Paging server">LDP Paging servers</a> may respond to requests for a
resource by redirecting to the first page of the resource and, with that, returning
@@ -684,132 +1230,7 @@
retrieve all the <a>in-sequence page resource</a>s without the <a>paged resource</a>
being added to or changed, so clients requiring such a guarantee
may not find all <a>paged resource</a>s usable in practice.
- </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.
- </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>
-
-<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/>.
-@prefix ldp: <http://www.w3.org/ns/ldp#>.
-@prefix o: <http://example.org/ontology/>.
-@base <http://example.org/customer-relations>.
-
-<>
- a o:CustomerRelations;
- dcterms:title "The customer information for Example Co.";
- o:client <#JohnZSmith>, <#BettyASmith>, <#JoanRSmith>.
-
-<#JohnZSmith>
- a foaf:Person;
- o:status o:ActiveCustomer;
- foaf:name "John Z. Smith".
-<#BettyASmith>
- a foaf:Person;
- o:status o:PreviousCustomer;
- foaf:name "Betty A. Smith".
- <#JoanRSmith>
- a foaf:Person;
- o:status o:PotentialCustomer;
- foaf:name "Joan R. Smith".</pre>
-
- <p>
- Because the server includes a <code>Link: <http://example.org/customer-relations?p=2>; rel='next'</code>
- response header, and the status code is 2xx (<code>2NN Contents of 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.
- </p>
- <p>
- The following example is the result of retrieving
- the next page:
- </p>
-
-<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.
-#
-@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/>.
-@prefix ldp: <http://www.w3.org/ns/ldp#>.
-@prefix o: <http://example.org/ontology/>.
-@base <http://example.org/customer-relations>.
-
-<>
- o:client <#GlenWSmith>, <#AlfredESmith>.
-
-<#GlenWSmith>
- a foaf:Person;
- o:status o:ActiveCustomer, o:GoldCustomer;
- foaf:name "Glen W. Smith".
-
-<#AlfredESmith>
- a foaf:Person;
- o:status o:ActiveCustomer, o:BronzeCustomer;
- foaf:name "Alfred E. Smith".
- </pre>
- <p>
- In this example, there are only two customers provided in the
- second page. To indicate this is also the last page, the server omits the <code>Link: rel='next'</code>
- header in its response. The client combines the representations as appropriate for the media type;
- in this case, an RDF graph merge is the logical choice.
- </p>
- <!-- TODO: show it both ways; if a competing change hit the container, or not -->
- <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 <a>paged resource</a> on the server, unless the client also
- verifies that the <a>paged resource</a> has not changed. For example, after the server constructs the
- the first page representation, another
- actor could delete <code>client#BettyASmith</code> from the server.
+ A detailed example is provided in <a href="#ldpp-ex-mx" class="sectionRef"></a>.
</p>
</section>
<section class="informative" id="ldpr-impl">
@@ -824,9 +1245,10 @@
its next page links, for example.
</p>
<p>
- Observe that in the preceding example, it is likely that the <var>page n</var> URIs are all of the form
+ Observe that in the <a href="#ldpp-ex-mx" class="sectionRef">preceding examples</a>,
+ the <var>page n</var> URIs are all of the form
<code>http://example.org/customer-relations?p=<var>n</var></code>,
- where <var>n</var> is <var>2..n</var>.
+ where <var>n</var> is <var>2..n</var>. This is likely true in general practice.
If the server allocates <code>o:client</code> representations to pages randomly, it's not obvious how to avoid
keeping per-client state of one kind or another on the server while still sending all the representations on
at least one page. In the common case where the list has an
@@ -1238,7 +1660,9 @@
discover <dfn><abbr title="Linked Data Platform Containers">LDPCs</abbr></dfn>.</p>
<div class="ldp-issue-pending" id="what-the-new-container"><p class="ldp-issue-title">For Discussion</p>
- <p>Are we attempting to define a new type of container here? If not, should delete the clause.</p>
+ <p>Are we attempting to define a new type of container here? If not, should delete the clause.
+ Some support for doing so on the mailing list week of 7 July 2014.
+ </p>
</div>
<section id="ldpc-isldpr"><h2 class="normal">Each Linked Data Platform Paging Container MUST also be
@@ -1248,7 +1672,7 @@
<section id="ldpc-onsamepage"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MUST
ensure that the <a title="membership triples">membership triple</a> and
- <a title="containment triples">containment triple</a> for each member are on the
+ <a title="containment triples">containment triple</a> for each member are part of the
same <a>in-sequence page resource</a>, whenever both triples are present in the page sequence
for a <a title="paged resource">paged LDPC</a>.
</h2></section>
@@ -1452,7 +1876,7 @@
</section>
-<section class='appendix informative'>
+<section class='appendix informative' id="acks">
<h2>Acknowledgements</h2>
<p>The following people have been instrumental in providing thoughts, feedback,
@@ -1474,6 +1898,7 @@
<!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-paging-20140930/">Candidate Recommendation Draft</a></em></blockquote> wah -->
<!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-paging-20140730/">Last Call Draft</a></em></blockquote> -->
<ul>
+ <li>2014-07-09 - Move paging example into "intro" chapter 4 (JA) </li>
<li>2014-07-08 - Resolve a set of editorial to-dos (JA) </li>
<li>2014-07-07 - Clients must consent to/invite paging per 20140630 resolution 2 (JA) </li>
<li>2014-07-07 - Rename single-page resource to in-sequence page resource per 20140630 resolution 3 (JA) </li>