--- a/ldp-paging.html Wed Nov 05 15:27:11 2014 -0500
+++ b/ldp-paging.html Wed Nov 05 15:47:55 2014 -0500
@@ -112,15 +112,6 @@
, status: "N/A"
, publisher: "Wikipedia"
},
- "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"
- },
"LDP-PAGING-TESTSUITE": {
title: "Linked Data Platform Paging 1.0 Test Cases"
, href: "https://dvcs.w3.org/hg/ldpwg/raw-file/tip/tests/ldp-paging-testsuite.html"
@@ -395,8 +386,8 @@
<dt><dfn>first page link</dfn></dt>
<dd>A link to the first <a title="In-sequence page resource">in-sequence page resource</a> <var>P<sub>1 (first)</sub></var>
- of a <a>page sequence</a>. The first page is the one that a LDP paging server
- redirects to (<code>303</code> response) or provides the representation of (<code>2NN</code> response) in response
+ of a <a>page sequence</a>. The first page is the one that a LDP Paging server
+ redirects to (<code>303</code> response) in response
to a retrieval request for the <a>paged resource</a>'s URI.
Syntactically, a
HTTP <code>Link <<var>P<sub>1</sub></var>>; rel='first'</code>
@@ -807,205 +798,6 @@
</section>
-<section id="ldpp-ex-paging-2nn">
-<h2>Removing redirection latency when paging</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; max-triple-count="500"
-Prefer: contents-of-related
-</pre>
-
- <p>
- 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"><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
-
-@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>max-triple-count</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; max-triple-count="500"
-Prefer: contents-of-related
-</pre>
- <p>
- The server's response is shown below:
- </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
-
-@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 <a>page sequence</a>, 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-other-links">
<h2>Optional paging links</h2>
@@ -1020,7 +812,7 @@
<ul>
<li>
- The <a title="first page link">first page</a>'s <a href="#ldpp-ex-paging-2nn-resp1">response message</a> might also have the following links:
+ The <a title="first page link">first page</a>'s <a href="#ldpp-ex-paging-303-resp2">response message</a> might also have the following links:
<pre class="example">
Link: <>; rel='first'
Link: <http://example.org/customer-relations?p=2>; rel='last'
@@ -1035,7 +827,7 @@
</pre>
</li>
<li>
- The <a title="last page link">last page</a>'s <a href="#ldpp-ex-paging-2nn-resp2">response message</a> might also have the following links:
+ The <a title="last page link">last page</a>'s <a href="#ldpp-ex-paging-303-resp3">response message</a> might also have the following links:
<pre class="example">
Link: <http://example.org/customer-relations?page1>; rel='first'
Link: <http://example.org/customer-relations?page1>; rel='prev'
@@ -1286,58 +1078,16 @@
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, or choose not to page the resource at all.
</h2></section>
-
- <div class="atrisk" id="atrisk-2NN"><p class="atrisktext">Feature At Risk</p>
- <p>The LDP Working Group proposes incorporation of the features described in the next compliance clause.</p>
- <ul>
- <li><p>
- A <a href="http://lists.w3.org/Archives/Public/www-tag/2013Dec/0041.html">December 2013 TAG discussion</a> started,
- whose goal is to reduce the need for two request-response round trips down to one when retrieving what
- turns out to be the first page of a paged resource, by defining a new
- HTTP response code in the <code>2xx</code> or <code>3xx</code> class that would allow a server to
- respond to <code>GET request-uri</code> requests with the representation of the first page
- (whose URI is <code>first-page-uri</code>, not <code>request-uri</code>) of a multi-page response.
- </p></li>
- <li><p>
- 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
- 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
- <a href="https://github.com/w3ctag/spec-reviews/blob/master/2014/04/http-209.md">the TAG's draft comments, item 2</a>.
- Note: nothing prevents servers or clients from using <code>303 See Other</code> responses to
- requests for <a title="Paged resource">paged resources</a>. The only significant differences between 303 and 2NN responses
- are the extra round trip required for the client to retrieve the representation of the first page when using 303,
- and the non-cacheable nature of 303 responses.
- </p></li>
- <li><p>
- Once LDP-Paging is a
- Candidate Recommendation, the LDP WG will make an assessment based on the status at IETF,
- working with the W3C Director, to either use the newly defined response code 2NN
- as documented in this section or to revert to a classic
- <code>303</code> response pattern.
- </p></li>
- </ul>
- </div>
-
+
<section id="ldpr-status-code"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> SHOULD NOT
- initiate paging unless the client has indicated it understands LDP Paging or that it is prepared to
- process <code>2NN Contents of Related</code> responses [[!2NN]].
+ initiate paging unless the client has indicated it understands LDP Paging.
<a title="LDP Paging server">LDP Paging servers</a> initiating paging SHOULD respond
to successful <code>GET</code> requests with any <a title="Paged resource">paged resource</a>
as the <code>Request-URI</code> in one of the following ways:</h2>
<ul>
<li>
- If the client supports <code>2NN</code> responses, respond
- with HTTP status code <code>2NN Contents of Related</code> and the first
- <a>in-sequence page resource</a>'s representation.
- </li>
- <li>
- If the client supports paging but not <code>2NN</code> responses,
- respond with
+ If the client supports paging, respond with
status code <code>303 See Other</code> and a <code>Location</code> response header that identifies
the first <a>in-sequence page resource</a>.
The only standard means defined by LDP paging for a client to signal a server that the client
@@ -2098,7 +1848,7 @@
<em>Summary</em>
<ul>
- <li></li>
+ <li>Removed "Feature at Risk" content for <code>2NN Contents of Related</code> status code and usage.</li>
</ul>
<!--
<em>Summary</em>
@@ -2119,6 +1869,7 @@
<!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-paging-20140930/">Candidate Recommendation Draft</a></em></blockquote> wah -->
<!--
<ul>
+ <li>2014-11-05 - Removed "at risk" content for "2NN Contents of Related" status code and usage (SS) </li>
<li>2014-11-05 - Removed "at risk" markers for max-member-count and max-kbyte-count, honor all hints and clients should expect paging (SS) </li>
<li>2014-10-10 - Clarified "new protocol" in 4.2, hyper-linked max-member-count to LDPCs per 10/10 public comments email (JA) </li>
<li>2014-09-26 - Added non-norm items about extensions to supply client requested ordering (SS) </li>