--- a/ldp-paging.html Wed Jul 09 11:18:31 2014 -0400
+++ b/ldp-paging.html Wed Jul 09 13:22:55 2014 -0400
@@ -158,6 +158,25 @@
, status: "Proposed Standard"
, publisher: "IETF"
},
+ "2NN": {
+ title: "The Hypertext Transfer Protocol (HTTP) Status Code 2NN (Contents of Related)"
+ , href: "http://www.w3.org/2014/02/2xx/draft-prudhommeaux-http-status-2NN.xml"
+ , authors: [
+ "E. Prud'hommeaux"
+ ]
+ , status: "Internet-Draft"
+ , publisher: "IETF"
+ },
+ "REL-CANONICAL": {
+ title: "The Canonical Link Relation"
+ , href: "http://tools.ietf.org/html/rfc6596"
+ , authors: [
+ "M. Ohye",
+ "J. Kupke"
+ ]
+ , status: "Informational"
+ , publisher: "IETF"
+ },
"RFC5005": {
title: "Feed Paging and Archiving"
, href: "http://tools.ietf.org/html/rfc5005"
@@ -286,10 +305,16 @@
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.
+ A detailed example of paging is provided in <a href="#ldpp-ex-mx" class="sectionRef"></a>.
</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>. A detailed example is provided in <a href="#ldpp-ex-mx" class="sectionRef"></a>.
+ When a <a>paged resource</a> is also an LDPC, some additional efficiencies become possible in cases
+ where the server predictably assigns members to pages and is able to communicate its assignment
+ algorithm to clients. <a href="#ldpc" class="sectionRef"></a> defines a facility to communicate
+ the sort order of member-to-page assignments, to handle that common implementation algorithm.
+ </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]].
</p>
</section>
@@ -475,13 +500,11 @@
<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="#ldpc" class="sectionRef"></a>: <b>normative</b></li>
<li><a href="#security" class="sectionRef"></a>: <b>non-normative</b></li>
+ <li><a href="#ldpr-impl" class="sectionRef"></a>: <b>non-normative</b></li>
<li><a href="#acks" class="sectionRef"></a>: <b>non-normative</b></li>
+ <li><a href="#history" 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>
@@ -516,7 +539,7 @@
</pre>
<p>
- The server responds with status code <code>200 OK</code> and the following representation:
+ The server response is:
</p>
<em>Response:</em>
@@ -618,9 +641,9 @@
</pre>
<p>
- The server responds with <code>303 See Other</code>, and
+ The server's response contains a <code>303 See Other</code> status code and
a <code>Location: http://example.org/customer-relations?page1</code> HTTP response header
- identifying the target resource.
+ identifying the target resource, as shown below:
</p>
<em>Response:</em>
@@ -642,8 +665,7 @@
Prefer: return=representation; page-size="500 rdf-triples"
</pre>
<p>
- The server responds with status code <code>200 OK</code>,
- and the following representation:
+ The server's response is shown below:
</p>
<em>Response:</em>
@@ -726,7 +748,7 @@
Prefer: return=representation; page-size="500 rdf-triples"
</pre>
<p>
- The server responds with status code <code>200 OK</code> and the following representation:
+ The server's response is shown below:
</p>
<em>Response:</em>
@@ -819,11 +841,12 @@
</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.
+ The server's response is shown below; it includes a
+ <a href="#atrisk-2NN">status code <code>2NN Contents of Related</code></a>,
+ and a representation payload.
</p>
<p>
- As was true in the <a href="#ldpp-ex-paging-303"></a><code>303 See Other</code> approach</a>,
+ 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.
@@ -927,7 +950,7 @@
Prefer: contents-of-related
</pre>
<p>
- The server responds with status code <code>200 OK</code> and the following representation:
+ The server's response is shown below:
</p>
<em>Response:</em>
@@ -941,9 +964,6 @@
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/>.
@@ -1005,7 +1025,7 @@
<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 href="#ldpp-hints">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>
@@ -1048,61 +1068,48 @@
</h2>
</section>
+ <section id="ldpp-client-paging-incomplete"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a>
+ SHOULD NOT present <a title="paged resource">paged resources</a> as coherent or
+ complete, or make assumptions to that effect.
+ </h2></section>
+
</section>
<section id="ldpp-hints">
-<h2>Client hints</h2>
- <p>
- Clients can provide paging-related hints to influence the server's choices.
- </p>
-
-<section id="ldpp-hints-summary">
-<h3>Summary</h3>
-
+<h2>Client preferences</h2>
<p>
- This specification introduces new ...
- <!-- TODO: fill in summary -->
- <!--
- parameters on the HTTP <code>Prefer</code> request header's
- <code>return=representation</code> preference [[!RFC7240]], used optionally by clients to
- supply a hint to help the server form a response that is most appropriate to
- the client's needs. The LDP-defined parameters suggest the portion(s) of a resource's state that the
- client application is interested in and, if received, is likely to be
- processed. LDP Containers with large numbers of associated documents
- and/or members will have large representations, and many client
- applications may be interested in processing only a subset of the LDPC's
- information (for example, only membership triples or only containment triples),
- resulting in a potentially large savings in server, client,
- and network processing.
- </p>
-
- <p>
- Non-normative note: LDP server implementers should carefully consider the effects of these
- preferences on caching, as described in section 2 of [[!RFC7240]].
+ LDP Paging clients <a href="#ldpp-client-advertise">must provide paging-related hints</a>
+ in order to influence an LDP Paging server's choices.
</p>
<p>
- Non-normative note: [[!RFC7240]] recommends that server implementers include a
- <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.
- -->
+ This specification introduces new
+ parameters on the HTTP <code>Prefer</code> request header's
+ <code>return=representation</code> preference [[!RFC7240]], <a href="#ldpp-client-advertise">used by clients</a> to
+ supply a preference that helps the server form a response that is most appropriate to
+ the client's needs. The preference serves several purposes:
+ <ul>
+ <li>It signals the client's support for LDP Paging to the request server</li>
+ <li>It communicates the client's maximum desired size for a response representation</li>
+ </ul>
</p>
-
-</section> <!-- Prefer summary -->
+ <blockquote>
+ <em>Non-normative note</em>: LDP server implementers should carefully consider the effects of these
+ preferences on caching, as described in section 2 of [[!RFC7240]].
+ </blockquote>
+ <blockquote>
+ <em>Non-normative note</em>: [[!RFC7240]] recommends that server implementers include a
+ <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.
+ </blockquote>
-<section id="prefer-rules">
-<h3>Specification</h3>
-
- <section id="ldpp-hints-page-size"><h2 class="normal">
- 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
+ <p>
+ LDP Paging defines <code>page-size</code> as a new parameter on the existing
+ HTTP <code>Prefer</code> request header's
+ <code>return=representation</code> preference [[!RFC7240]].
+ A client communicates its hint to the server by adding the
+ request header with a
+ <code>return=representation</code> preference that includes a
<code>page-size</code> parameter whose value adheres to the following syntax:
</h2>
<pre><code>
@@ -1113,7 +1120,7 @@
</code></pre>
<blockquote>
<p>
- Where <code>WSP</code> is whitespace [[!RFC5234]],
+ <code>WSP</code> is whitespace [[!RFC5234]],
<code>DIGIT</code> is an integer between zero and nine [[!RFC5234]],
<code>DQUOTE</code> is a double quote [[!RFC5234]],
and
@@ -1123,26 +1130,17 @@
<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 no maximum desired size was specified; in the latter case the server
- can select whatever page size it deems appropriate.
+ can select whatever page size it deems appropriate, or choose not to page the resource at all.
</p>
</blockquote>
- </section>
-
-</section> <!-- Prefer specification -->
+ </p>
-<section id="prefer-examples" class="informative">
-<h3>Examples</h3>
-
- <p id="prefer-examples-direct-minimal-container-only1">
+ <p id="prefer-examples-500-triples">
Clients interested in receiving at most 500 RDF triples per <a title="in-sequence page resource">page</a>
- would use add this HTTP header on a <code>GET</code> request:
+ would use add this HTTP header on a <code>GET</code> request, as shown in <a href="#ldpp-ex-paging-303" class="sectionRef"></a>:
<code>Prefer: return=representation; page-size="500 rdf-triples"</code>
</p>
-
-</section> <!-- Prefer examples -->
-
-
</section> <!-- Paging hints -->
</section> <!-- Client constraints -->
@@ -1231,53 +1229,7 @@
being added to or changed, so clients requiring such a guarantee
may not find all <a>paged resource</a>s usable in practice.
A detailed example is provided in <a href="#ldpp-ex-mx" class="sectionRef"></a>.
- </p>
-</section>
-<section class="informative" id="ldpr-impl">
-
-<h3>Paging without maintaining session state</h3>
- <p>
- Server implementers naturally have concerns when they are expected to maintain per-client state
- because of the scalability limitations that per-client state implies.
- LDP Paging carries no such requirement, although this may not be obvious at first glance.
- Since URLs are opaque to clients [[WEBARCH]], a server
- is free to encode the information required for it to know where to start the next page inside
- its next page links, for example.
- </p>
- <p>
- 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>. 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
- ordering (either a natural one or one imposed by the implementation) however, it is easy to avoid
- keeping per-client state on the server.
- </p>
- <p>
- One trivial case is "fixed order"; if the server always sends
- <code>o:client</code> representations in the order
- <code>#JohnZSmith, #BettyASmith, #JoanRSmith, #GlenWSmith, #AlfredESmith</code> (or indeed,
- in <i>any</i> predictable order), then it can put the "last seen" identifier in the <a>next page link</a>
- of each <a>in-sequence page resource</a> as it is retrieved <em>by each client</em>. The "session state"
- is, in effect, kept by the client.
- In this case, the <a>next page link</a> in the first page might be:
- </p>
- <pre class="example" id="paging-no-session-state1">
- Link: <http://example.org/customer-relations?resumeafter=JoanRSmith>; rel='next'
- </pre>
- <p>
- If the server also supports <a>backward traversal</a>, then the second page's
- <a>previous page link</a> might be:
- </p>
- <pre class="example" id="paging-no-session-state2">
- Link: <http://example.org/customer-relations?resumebefore=GlenWSmith>; rel='next'
- </pre>
- <p>
- Keep in mind that this is an exemplary server implementation decision; it is not prescribed by
- LDP Paging, and other choices are certainly possible. As long as the URIs used in links
- are opaque to clients, any choice is permissible.
+ See <a href="#ldpr-impl" class="sectionRef"></a> for server implementation considerations.
</p>
</section>
@@ -1312,7 +1264,7 @@
<section id="ldpp-prefer"><h2 class="normal"><a title="LDP Paging server">LDP Paging servers</a>
SHOULD respect all of a client's <a href="#ldpp-hints">LDP-Paging-defined hints</a>, for example
- <a href="#ldpp-hints-page-size">the largest page size</a>
+ <a href="#ldpp-hints">the largest page size</a>
the client is interested in processing,
to influence the amount of data returned in representations.
</h2></section>
@@ -1332,8 +1284,7 @@
For the purposes of drafting this section, we assume that the
new code's value is <code>2NN Contents of Related</code>,
and its definition is given by the
- <a href="http://www.w3.org/2014/02/2xx/draft-prudhommeaux-http-status-2NN.xml">draft-prudhommeaux-http-status-2nn</a>
- IETF draft, whose content evolved from
+ IETF draft [[!2NN]], whose content evolved from
<a href="http://lists.w3.org/Archives/Public/www-tag/2014Jan/0023.html">an LDP extrapolation from TAG discussions</a>,
<a href="http://lists.w3.org/Archives/Public/www-tag/2014Jan/0015.html">Henry Thompson's strawman</a>,
with the substitution of 2NN for 2xx as suggested in
@@ -1357,7 +1308,8 @@
<a title="LDP Paging server">LDP Paging servers</a> SHOULD respond
with HTTP status code <code>2NN Contents of 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 such as <code>303 See Other</code> MAY be used.
+ as the <code>Request-URI</code> when the request indicates the client's support for that status code [[!2NN]],
+ although any appropriate code such as <code>303 See Other</code> MAY be used.
</h2></section>
<section id="ldpr-guarantee-show-unchanged"><h2 class="normal">
@@ -1426,7 +1378,7 @@
The link's
context URI identifies the <a>in-sequence page resource</a> being retrieved,
target URI identifies the <a>paged resource</a>,
- link relation type is <code>canonical</code>,
+ link relation type is <code>canonical</code> [[!REL-CANONICAL]],
and
link extension parameters include the parameter name <code>etag</code>
and a corresponding parameter value identical to the ETag [[!RFC7232]]
@@ -1511,11 +1463,34 @@
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="ldp-issue-pending" id="what-the-new-container"><p class="ldp-issue-title">For Discussion</p>
+ <p>
+ Need to clarify expected behavior(s).
+ Some support for doing so on the mailing list week of 7 July 2014.
+ </p>
+ <p>
+ Strawman based on Sandro's response: add to the normative requirement below:
+ <blockquote>
+ <em>Non-normative note:</em>
+ <a title="LDP Paging server">LDP Paging servers</a> could choose to make any resource
+ available <em>only</em> as a paged resource. One consequence of the prohibition on initiating paging
+ when interacting with non-paging-aware clients is: if such a server
+ receives a request for a paged-only resource, and the request does not signal that
+ the client is paging-aware, then the server has to reject the request, most likely
+ with a <code>4xx</code> status code. This avoids the situation where a non-paging-aware client
+ blindly follows a <code>303</code> redirect, retrieves that resource (which the server, but not the client,
+ knows to contain only the first page of the paged resource's state), and upon receiving the <code>200 OK</code>
+ status code concludes that it now has the <em>entire</em> representation of the paged resource's state (instead
+ of only having a representation of the subset assigned to the first page).
+ </blockquote>
+ </p>
+ </div>
+
<section id="ldpr-pagingGET-only-paging-clients"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MUST NOT
initiate paging unless the client has indicated it understands paging.
The only standard means defined by LDP paging for a client to signal a server that the client
- understands paging is via the <a href="#ldpp-hints-page-size">client hint</a> defined below;
+ understands paging is via the <a href="#ldpp-hints">client preference</a> defined for this purpose;
other implementation-specific means could also be used.
</h2></section>
@@ -1761,33 +1736,6 @@
</section> <!-- h1 LDPC -->
-
-<section id="base-specs" class="informative">
-<h1>Notable information from normative references</h1>
-<p>
-While readers, and especially implementers, of LDP are assumed to understand the information in its normative
-references, the working group has found that certain points are particularly important to understand.
-For those thoroughly familiar with the referenced specifications, these points might seem obvious, yet
-experience has shown that few non-experts find all of them obvious. This section enumerates these topics;
-it is simply re-stating (non-normatively) information locatable via the normative references.
-</p>
-
-<section id="specs-paging" class="informative">
-<h2>Feed paging and archiving</h2>
-Reference: [[RFC5005]]
-
- <section id="ldp-paging-incomplete"><h2 class="normal">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]].
- </h2></section>
-
-</section>
-
-</section> <!-- Base specs -->
-
-<section>
-
<!-- Removed for action-113
<section>
<h1>HTTP Status Code Definitions</h1>
@@ -1875,6 +1823,54 @@
access control policy.
</section>
+<section class="appendix informative" id="ldpr-impl">
+
+<h2>Paging LDPRs without maintaining server-side session state</h2>
+ <p>
+ Server implementers naturally have concerns when they are expected to maintain per-client state
+ because of the scalability limitations that per-client state implies.
+ LDP Paging carries no such requirement, although this may not be obvious at first glance.
+ Since URLs are opaque to clients [[WEBARCH]], a server
+ is free to encode the information required for it to know where to start the next page inside
+ its next page links, for example.
+ </p>
+ <p>
+ 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>. 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
+ ordering (either a natural one or one imposed by the implementation) however, it is easy to avoid
+ keeping per-client state on the server.
+ </p>
+ <p>
+ One trivial case is "fixed order"; if the server always sends
+ <code>o:client</code> representations in the order
+ <code>#JohnZSmith, #BettyASmith, #JoanRSmith, #GlenWSmith, #AlfredESmith</code> (or indeed,
+ in <i>any</i> predictable order), then it can put the "last seen" identifier in the <a>next page link</a>
+ of each <a>in-sequence page resource</a> as it is retrieved <em>by each client</em>. The "session state"
+ is, in effect, kept by the client.
+ In this case, the <a>next page link</a> in the first page might be:
+ </p>
+ <pre class="example" id="paging-no-session-state1">
+ Link: <http://example.org/customer-relations?resumeafter=JoanRSmith>; rel='next'
+ </pre>
+ <p>
+ If the server also supports <a>backward traversal</a>, then the second page's
+ <a>previous page link</a> might be:
+ </p>
+ <pre class="example" id="paging-no-session-state2">
+ Link: <http://example.org/customer-relations?resumebefore=GlenWSmith>; rel='next'
+ </pre>
+ <p>
+ Keep in mind that this is an exemplary server implementation decision; it is not prescribed by
+ LDP Paging, and other choices are certainly possible. As long as the URIs used in links
+ are opaque to clients, any choice within the constraints of all normative references is permissible.
+ </p>
+</section>
+
<section class='appendix informative' id="acks">
<h2>Acknowledgements</h2>
@@ -1898,6 +1894,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 - Clean up clients chapter, references, non/normative section listing in conformance, kitchen sink (JA) </li>
<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>