UserPreferences

PageListTemplates


Abstract

Reworks the Collection List Template mechanism as a combination between what we already had and what Robert S. is proposing in his Seek draft.

Specific points:

Status

Proposal

Rationale

Proposal

9. Collection List Templates

Collections can contain extremely large numbers of resources. A naive client such as a web spider or web browser would be overwhelmed if the response to a GET contained every entry in the feed, and the server would waste large amounts of bandwidth and processing time on clients unable to handle the response.

For this reason, Introspection documents refer to collections not with IRIs but with IRI templates contained in the "app:list-template" child of "app:collection". An IRI Template is a string containing one or more embedded tokens representing parameters used to limit the set of returned resources.

To produce an IRI that can be used to retrieve a partial or full listing of the members of a collection, each token may be replaced with an appropriate value for that particular token. An IRI template MUST, after such substitution has been performed, constitute a syntactically valid IRI.

This document defines five replacement tokens that MAY be used within IRI templates:

None of the parameters are required. Servers MAY choose to specify additional tokens.

Replacement tokens may appear anywhere within the IRI template string and may be used together to form composite filters for lists.

For example, suppose the client is supplied this IRI template

  http://example.org/entries/{page}?c={count}&o={offset}

If the client wants to return only the first five entries in the second page of results, it would substitute {page}=2, {count}=5, and {offset}=0 to achieve:

  http://example.org/entries/2?c=5&o=0

9.1 Named List Templates

List templates appearing within Introspection documents MAY be named in order to provide publishers a way of differentiating between various list options.

For instance, a server implementation that supports categorization of entries may wish to allow a collection's members to be filtered and listed according to specific categories. A list-template for each category may be specified:

  <collection 
    title="Blog"
    href="...">    
    <list-template name="Technology">http://example.org/entries?cat=technology&c={count}&o={offset}</list-template>
    <list-template name="Work Stuff">http://example.org/entries&cat=work&c={count}&o={offset}</list-template>
  </collection>

9.2 Default List Template

The ordering of list templates within an Introspection document collection element is significant. The first list-template element contained in the collection is considered to be the default list template for the collection. User agents displaying the list of templates to a user SHOULD present those templates in the same order they appear within the introspection document.

9.3 Collection List Paging

The IRI's created through the token-replacement process MUST reference Atom feed documents listing the selected subset of collection members. The returned Atom feed may contain only a partial listing of all matching resources. For instance, out of a set of 100 entries edited between January 1st of 2005 and December 31st of 2005, an IRI constructed with a {begin} value of 2005-01-01T00:00:00Z and {end} of 2005-12-31T12:00:00T may only return first 10 matching entries. In order to allow clients access to the remaining members of the list, the feed MAY contain link elements with rel attribute values of 'next', 'previous', 'start' and 'end' that may be used to navigate through the complete set of matching entries.

For instance, suppose the client is supplied this IRI template

  http://example.org/entries/{page}?b={begin}&e={end}

The client replaces the tokens to receive page 1 of all entries updated between January 1st of 2005 and December 31st of 2005.

  http://example.org/entries/1?b=2005-01-01T00:00:00Z&e=2005-12-31T00:00:00Z

Assuming a set of 100 matching entries in the collection and a {page} size of 10 entries per page, the resulting Atom feed document represents the first page in a linked set of 10 feed documents. Within each feed document, 'next' and 'prev' link elements reference the preceding and subsequent feed documents in the set. The 'start' link element references the first feed document in the set. The 'end' link element references the final feed document in the set.

http://example.org/entries/1?b=2005-01-01T00:00:00Z&e=2005-12-31T00:00:00Z

  <feed xmlns="http://www.w3.org/2005/Atom">
    ...
    <link rel="start"
          href="http://example.org/entries/1?b=2005-01-01T00:00:00Z&e=2005-12-31T00:00:00Z" />
    <link rel="next"
          href="http://example.org/entries/2?b=2005-01-01T00:00:00Z&e=2005-12-31T00:00:00Z" />
    <link rel="last"
          href="http://example.org/entries/10?b=2005-01-01T00:00:00Z&e=2005-12-31T00:00:00Z" />
  </feed>

http://example.org/entries/2?b=2005-01-01T00:00:00Z&e=2005-12-31T00:00:00Z

  <feed xmlns="http://www.w3.org/2005/Atom">
    ...
    <link rel="start"
          href="http://example.org/entries/1?b=2005-01-01T00:00:00Z&e=2005-12-31T00:00:00Z" />
    <link rel="previous"
          href="http://example.org/entries/1?b=2005-01-01T00:00:00Z&e=2005-12-31T00:00:00Z" />
    <link rel="next"
          href="http://example.org/entries/3?b=2005-01-01T00:00:00Z&e=2005-12-31T00:00:00Z" />
    <link rel="last"
          href="http://example.org/entries/10?b=2005-01-01T00:00:00Z&e=2005-12-31T00:00:00Z" />
  </feed>

Impacts

Notes


CategoryProposals