--- a/ldp.html Thu Nov 07 15:29:34 2013 -0500
+++ b/ldp.html Mon Nov 11 16:33:38 2013 -0500
@@ -133,6 +133,15 @@
]
, status: "Proposed Standard"
, publisher: "IETF"
+ },
+ "RFC5005": {
+ title: "Feed Paging and Archiving"
+ , href: "http://tools.ietf.org/html/rfc5005"
+ , authors: [
+ "M. Nottingham"
+ ]
+ , status: "Proposed Standard"
+ , publisher: "IETF"
}
},
};
@@ -317,22 +326,35 @@
<dd>The predicate of all a LDPC's <a title="Membership triples">membership triples</a>.
<p></p></dd>
+ <dt><dfn>Non-member resource</dfn></dt>
+ <dd>A resource associated with a LDPC by a server for the purpose of enabling clients to
+ retrieve a subset of the LDPC's state, namely the subset that omits the LDPC's membership triples.
+ In other words, the union of the non-member resource's state and the LDPC's membership triples
+ exactly equals the LDPC's state.
+ <p></p></dd>
+
<dt><dfn>Paged resource</dfn></dt>
<dd>A resource whose representation may be too large to fit in a single HTTP response, for which an
LDP server offers a sequence of single-page resources. When the representations of the sequence's resources
- are combined by a client, the client has a (potentially incomplete) copy of the paged resource's
+ are combined by a client, the client has a (potentially incomplete or incoherent) copy of the paged resource's
state. If a paged resource <var>P</var> is an LDPR and is broken into a sequence of pages
(single-page resources) <var>P<sub>1</sub>, P<sub>2</sub>, ...,P<sub>n</sub></var>,
the representation of each <var>P<sub>i</sub></var> contains
a subset of the triples in <var>P</var>.
LDP allows paging of resources other than LDPRs, but does not specify how clients combine
- their representations. See <a href="#ldpr-Paging" class="sectionRef"></a> for additional details.
+ their representations. See <a href="#ldpr-Paging" class="sectionRef"></a> for additional details. For readers
+ familiar with paged feeds [[!RFC5005]], a paged resource is similar to a logical feed.
+ Any non-paged resource could be considered to be a paged resource consisting of exactly one page,
+ although there is no known advantage in doing so.
<p></p></dd>
<dt><dfn>Single-page resource</dfn></dt>
<dd>One of a sequence of related resources <var>P<sub>1</sub>, P<sub>2</sub>, ...,P<sub>n</sub></var>,
each of which contains a subset of the state
of another resource <var>P</var>. <var>P</var> is called the paged resource.
+ For readers
+ familiar with paged feeds [[!RFC5005]], a single-page resource is similar to a feed document and the same
+ coherency/completeness considerations apply.
</p><p>
Note: the choice of terms was designed to help authors and readers clearly differentiate between
the <a title="Paged resource"><em>resource being paged</em></a>, and the
@@ -341,11 +363,32 @@
close proximity. Both are resources in both the HTTP and RDF senses.
<p></p></dd>
- <dt><dfn>Non-member resource</dfn></dt>
- <dd>A resource associated with a LDPC by a server for the purpose of enabling clients to
- retrieve a subset of the LDPC's state, namely the subset that omits the LDPC's membership triples.
- In other words, the union of the non-member resource's state and the LDPC's membership triples
- exactly equals the LDPC's state.
+ <dt><dfn>first page link</dfn></dt>
+ <dd>A link to the first <a title="Single-page resource">single-page resource</a>
+ of a <a title="Paged resource">paged resource</a> <var>P</var>. Syntactically, a
+ HTTP <code>Link <<var>P<sub>1</sub></var>>; rel='first'</code>
+ header [[!RFC5988]].
+ <p></p></dd>
+
+ <dt><dfn>next page link</dfn></dt>
+ <dd>A link to the next <a title="Single-page resource">single-page resource</a>
+ of a <a title="Paged resource">paged resource</a> <var>P</var>. Syntactically, a
+ HTTP <code>Link <<var>P<sub>i</sub></var>>; rel='next'</code>
+ header [[!RFC5988]] where <var>i=2...n</var>.
+ <p></p></dd>
+
+ <dt><dfn>last page link</dfn></dt>
+ <dd>A link to the last <a title="Single-page resource">single-page resource</a>
+ of a <a title="Paged resource">paged resource</a> <var>P</var>. Syntactically, a
+ HTTP <code>Link <<var>P<sub>n</sub></var>>; rel='last'</code>
+ header [[!RFC5988]].
+ <p></p></dd>
+
+ <dt><dfn>previous page link</dfn></dt>
+ <dd>A link to the previous <a title="Single-page resource">single-page resource</a>
+ of a <a title="Paged resource">paged resource</a> <var>P</var>. Syntactically, a
+ HTTP <code>Link <<var>P<sub>i</sub></var>>; rel='prev'</code>
+ header [[!RFC5988]] where <var>i=1...n-1</var>.
<p></p></dd>
</dl>
@@ -804,50 +847,35 @@
<h3>Introduction</h3>
<p>It sometimes happens that a
resource is too large to reasonably transmit its representation in a
- single HTTP response. This will be especially true if the resource
- is a container whose
- representation includes many triples both from itself and
- from its member resources. A client could anticipate that a resource will be too large -
- for example, a client tool that accesses defects may assume that an
- individual defect will usually be of sufficiently constrained size
- that it makes sense to request all of it at once, but that the
- container of all the defects ever created will typically be too big.
- Alternatively, a server could recognize that a resource that has been
- requested is too big to return in a single message.</p>
- <p>
- To address this problem, resources should support a technique called Paging. Paging can be achieved with a
- simple pattern. For each resource, <code><resourceURL></code>, we define a new
- 'first page' resource. In this example, its URL will be <code><resourceURL>?firstPage</code>,
- but servers are free to construct the URL as they see fit.
+ single HTTP response.
+ To address this problem, resources should support a technique called Paging.
+ When a client retrieves such a resource, the server includes in its response
+ a link to the next part of the resource's state, at a URL of the server's choosing.
The triples in the representation of the each page of an LDPR
- are typically a subset of the triples in the resource
- - same subject, predicate and object.
+ are typically a subset of the triples in the resource.
</p>
<p><a title="LDP server">LDP servers</a> may respond to requests for a
- resource by returning the first page resource –
- using a <a href="#status-code-related-content"><code>209 Related Content</code></a> response
- with a <code>Location</code> header containing the URL for the page
- resource. Alternatively, clients may inspect the resource for a paged representation
- and use it preferentially when available.</p>
+ resource by returning the first page of the resource
+ with a <code>Link <next-page-URL>;type='next'</code> header containing the URL for the next page.
+ Clients inspect each response to see if additional pages
+ are available. Note that paging is lossy, as described in [[RFC5005]], and so (as stated there)
+ clients should not make any assumptions about a set of pages being a complete or
+ coherent snapshot of a resource's state.</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.
- To find out if the resource supports paging, and if it does the URL of the first page,
- the client makes a <code>OPTIONS</code> or <code>HEAD</code> request
- to <code>http://example.org/customer-relations</code>, 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/customer-relations?firstPage</code>, and
+ The client
+ retrieves the first page of <code>http://example.org/customer-relations</code>, and
the server responds with the following representation:
</p>
<pre class="example"># The following is the representation of
-# http://example.org/customer-relations?firstPage
+# http://example.org/customer-relations
# Requests on the ?firstPage URI will result in responses that include the following HTTP header
# Link: <http://example.org/customer-relations?p=2>; rel='next'
-# This Link header is how clients discover the URI of the next page in sequence.
+# This Link header is how clients discover the URI of the next page in sequence,
+# and that the resource supports paging.
@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/>.
@@ -910,6 +938,12 @@
final page. To indicate this is the last page, the server omits the <code>Link rel='next'</code>
header in its response.
</p>
+ <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 server. For example, after the server constructs the
+ the first page representation, another
+ actor could delete <code>client#BettyASmith</code> from the server.
+ </p>
</section>
<section id="ldpr-PagingGET">
@@ -920,7 +954,10 @@
and their associated <a title="Single-page resource">single-page resources</a>.
</p>
- <div id="ldpr-pagingGET-first-reqd-onbase" class="rule">4.10.2.1 <a title="LDP server">LDP servers</a> MUST
+ <div id="ldpr-pagingGET-first-reqd-onbase" class="rule">4.10.2.1 removed
+ </div>
+ <!-- Removed - action-113
+ <div id="ldpr-pagingGET-first-reqd-onbase" class="rule">4.10.2.1 <a title="LDP server">LDP servers</a> MAY
provide an HTTP <code>Link</code>
header whose target URI is the <em>first</em> <a title="Single-page resource">single-page resource</a>, and whose link relation type is <code>first</code> [[!RFC5988]]
in responses to <code>GET</code> requests with a <a title="Paged resource">paged resource</a> as the <code>Request-URI</code>.
@@ -932,11 +969,15 @@
then clients have no LDP-defined way to discover that the resource supports paging or the
URI of the first page.
</div>
+ -->
<div id="ldpr-pagingGET-first-allowed-onpages" class="rule">4.10.2.1.1
<a title="LDP server">LDP servers</a> MAY provide
- a <a href="#ldpr-pagingGET-first-reqd-onbase">first page link</a> when responding to
- requests with any <a title="Single-page resource">single-page resource</a> as the <code>Request-URI</code>.
+ a <a>first page link</a> when responding to
+ requests with any <a>single-page resource</a> as the <code>Request-URI</code>.
</div>
+ <div id="ldpr-pagingGET-last-allowed-onbase" class="rule">4.10.2.1.2 removed
+ </div>
+ <!-- Removed - action-113
<div id="ldpr-pagingGET-last-allowed-onbase" class="rule">4.10.2.1.2 <a title="LDP server">LDP servers</a> MAY
provide an HTTP <code>Link</code>
header whose target URI is the final <a title="Single-page resource">single-page resource</a>,
@@ -949,38 +990,43 @@
then clients can only find the final page using LDP-defined means
by following the <code>next</code> links to the end.
</div>
+ -->
<div id="ldpr-pagingGET-last-allowed-onpages" class="rule">4.10.2.1.3 <a title="LDP server">LDP servers</a> MAY
- provide a <a href="#ldpr-pagingGET-last-allowed-onbase">last page link</a>
+ provide a <a>last page link</a>
in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a> as the <code>Request-URI</code>.
</div>
<div id="ldpr-pagingGET-next-reqd" class="rule">4.10.2.2 <a title="LDP server">LDP servers</a> MUST
- provide an HTTP <code>Link</code>
- header whose target URI is the next page resource, and whose link relation type is <code>next</code> [[!RFC5988]]
+ provide a <a>next page link</a>
in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a>
<em>other than the final page</em>
as the <code>Request-URI</code>.
This is the mechanism by which clients can discover the URL of the next page.
</div>
<div id="ldpr-pagingGET-lastnext-prohibited" class="rule">4.10.2.2.1 <a title="LDP server">LDP servers</a> MUST NOT
- provide a <a href="#ldpr-pagingGET-next-reqd">next page link</a>
+ provide a <a>next page link</a>
in responses to <code>GET</code> requests with the final <a title="Single-page resource">single-page resource</a>
as the <code>Request-URI</code>.
- This is the mechanism by which clients can discover the end of the page sequence.
+ This is the mechanism by which clients can discover the end of the page sequence
+ as currently known by the server. The server is permitted to append pages over time,
+ so clients retrieving a final page several times can observe a "formerly last" page
+ having a <a>next page link</a> added.
</div>
<div id="ldpr-pagingGET-prev-allowed" class="rule">4.10.2.2.2 <a title="LDP server">LDP servers</a> MAY
- provide an HTTP <code>Link</code>
- header whose target URI is the previous page resource, and whose link relation type is <code>prev</code> [[!RFC5988]]
+ provide a <a>previous page link</a>
in responses to <code>GET</code> requests with any page resource <em>other than the first page</em>
as the <code>Request-URI</code>.
This is one mechanism by which clients can discover the URL of the previous page.
</div>
<div id="ldpr-pagingGET-firstprev-prohibited" class="rule">4.10.2.2.3 <a title="LDP server">LDP servers</a> MUST NOT
- provide a <a href="#ldpr-pagingGET-prev-reqd">previous page link</a>
+ provide a <a>previous page link</a>
in responses to <code>GET</code> requests with the <em>first</em> <a title="Single-page resource">single-page resource</a>
as the <code>Request-URI</code>.
This is one mechanism by which clients can discover the beginning of the page sequence.
</div>
- <div id="ldpr-pagingGET-next-reqd" class="rule">4.10.2.2.4 <a title="LDP server">LDP servers</a> MUST
+ <div id="ldpr-pagingGET-collection-reqd" class="rule">4.10.2.2.4 removed
+ </div>
+ <!-- Removed - action-113
+ <div id="ldpr-pagingGET-collection-reqd" class="rule">4.10.2.2.4 <a title="LDP server">LDP servers</a> MUST
provide an HTTP <code>Link</code>
header whose target URI is the <a title="Paged resource">paged resource</a>, and whose link relation type is <code>collection</code> [[!RFC5988]]
in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a>
@@ -989,11 +1035,16 @@
has been broken into pages, in cases where some other actor gives the client
a <a title="Single-page resource">single-page resource</a> URL.
</div>
+ -->
+ <div id="ldpr-pagingGET-redirect" class="rule">4.10.2.3 removed
+ </div>
+ <!-- Removed - action-113
<div id="ldpr-pagingGET-redirect" class="rule">4.10.2.3 <a title="LDP server">LDP servers</a>
that initiate paging for a LDPR MUST respond
by returning the first page resource using a <code>209 Related Content</code> response
with an HTTP <code>Location</code> header providing the first <a title="Single-page resource">single-page resource</a> URL.
</div>
+ -->
<div id="ldpr-pagingGET-page-type-reqd" class="rule">4.10.2.4 <a title="LDP server">LDP servers</a> MUST
provide an HTTP <code>Link</code>
header whose target URI is <code>http://www.w3.org/ns/ldp#Page</code>, and whose link relation type is <code>type</code> [[!RFC5988]]
@@ -1016,10 +1067,14 @@
This lowers server implementation effort.
</p>
+ <div id="ldpr-4_10_3_1" class="rule">4.10.3.1 removed
+ </div>
+ <!-- Removed - action-113
<div id="ldpr-4_10_3_1" class="rule">4.10.3.1 <a title="LDP server">LDP servers</a> MUST indicate their support for paging by
providing a <a href="#ldpr-pagingGET-first-reqd-onbase">first page link</a> when responding to HTTP <code>OPTIONS</code>
requests with a <a title="Paged resource">paged resource</a> as the <code>Request-URI</code>.
</div>
+ -->
</section> <!-- h3 -->
@@ -1980,7 +2035,7 @@
are used in the state of any one resource is not limited to any pre-defined
set.
</div>
- <div id="ldpr-4_5_5" class="rule">4.5.5 An <a title="LDP client">LDP client</a> MUST preserve all triples retrieved using HTTP <code>GET</code> that
+ <div id="ldpr-4_5_5" class="rule">4.5.5 A <a title="LDP client">LDP client</a> MUST preserve all triples retrieved using HTTP <code>GET</code> that
it doesn’t change whether it understands the predicates or not, when
its intent is to perform an update using HTTP <code>PUT</code>. The use of HTTP
<code>PATCH</code> instead of HTTP <code>PUT</code> for update avoids this burden for clients
@@ -2091,6 +2146,17 @@
</section>
+<section id="specs-paging" class="informative">
+<h1>Feed paging and archiving</h1>
+Reference: [[RFC5005]]
+
+ <div id="ldp-paging-incomplete" class="rule">9.4.1 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]].
+ </div>
+
+</section>
</div>
</section> <!-- Base specs -->
@@ -2120,7 +2186,8 @@
<!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130930/">Candidate Recommendation Draft</a></em></blockquote> wah -->
<ul>
- <li>2013-10-25 - Resolve ACTION-105 ACTION-105: Update spec to reflect 9/30 resolution moving Paging links to HTTP headers (JA)</li>
+ <li>2013-11-11 - Resolve ACTION-113 Update spec to reflect 11/04 resolution to remove 303 and have client use first/next links to detect paging (JA)</li>
+ <li>2013-10-25 - Resolve ACTION-105 Update spec to reflect 9/30 resolution moving Paging links to HTTP headers (JA)</li>
<li>2013-10-25 - Resolve ACTION-110 Update spec to reflect 10/21 resolution for normative changes to align vanilla/chocolate (JA)</li>
<li>2013-10-22 - Resolve ACTION-109 Update spec to reflect 10/21 resolution for ignoring triples on PUT (JA)</li>
<li>2013-10-22 - Resolve ACTION-107 Update spec to reflect 10/07 resolution on 5.6.2 LDPC deletion (JA)</li>