PaceReworkCollectionListing

Abstract

Reworks listing of collection members around the Collection Feed model described in PaceReworkProtocolModel.

• GET on the Collection URI returns an Atom Feed Document containing a server-selected subset of entries

• Feed document may contain an app:list-template extension element providing an IRI Template that may be used to request a client-defined subset of entries

• Description of IRI Templates is reworked to factor in extensibility / new replacement tokens

• Keeps the {index} token

Example:

Request
  GET /collection-uri HTTP/1.1.
  Host: example.org

Response
  HTTP/1.1 200 OK
  ...

  <?xml version="1.0"?>
  <feed xmlns="http://www.w3.org/2005/Atom">
    ...
    <app:list-template>http://example.org/entries/{index}</app:list-template>
  </feed>

Status

Withdrawn

Rationale

Combined with PaceReworkProtocolModel and PaceReworkCollectionMembership, this helps to significantly simplify the collection model and allows for listing of both server-defined subsets of entries AND client-defined subsets.

Proposal

5 Listing Collection Members

The Atom Feed Document returned by the Collection Resource
in response to a simple GET request against the Collection's 
IRI MAY contain a set of atom:entry elements representative
of server-defined subset of member resources.  Typically,
this subset will represent the most recently modified 
members of the collection.

5.1 List Templates

The Collection resource MAY choose to provide clients with
an alternative method of retrieving Atom Feed Documents
containing client-defined subsets of member resources by
including one 'app:list-template' extension element within 
the Atom Feed Document returned by the Collection resource.

The content value the 'app:list-template' element specifies
an IRI template as defined in Section 6 that may be 
processed to produce an IRI resolvable into an HTTP URL.
Clients may then perform a GET against the produced 
IRI to retrieve an Atom Feed Document representing the 
subset of member resources specified by the IRI.

  appListTemplate = element app:list-template {
    appCommonAttributes,
    ( appIriTemplate )
  }

  <feed xmlns="http://www.w3.org/2005/Atom">
    ...
    <app:list-template>http://example.org/{index}</app:list-template>
  </feed>  
  
6. IRI Templates

  An IRI Template is a string containing zero or more embedded
  tokens that when processed will produce a syntactically valid 
  IRI that is resolvable to an HTTP URL.

    appIriTemplate = xsd:string { pattern = ".+\{.+\}.*" }
    
  Processing an IRI Template involves substituting each contained
  token with a value representation appropriate for the token.
  
  This specification defines the token "{index}" to represent a
  pair of non-negative integer indices separated by a dash 
  character, e.g. 0-10. The index values are 0-based and select 
  m embers f rom t he c ollection b ased o n t he m ember's i ndex, w ith t he 
  set of members ordered in reverse chronological order according
  to the value of their atom:updated property (most recently 
  updated member first).  The specified range is considered to
  be a closed set -- if an entry matches one of the range exactly
  it MUST be included in the response.  If no members fall within
  the specified range, the server MUST respond with an Atom Feed
  containing no entries
  
  For example, suppose the client is supplied this IRI template:
  
    http://example.org/blog/entries/{index}
    
  If the client wishes to retrieve a listing of the 15 most recently 
  updated entries in the collection, it would substitute the brace
  delimited token {index} with the value 0-14, producing:
  
    http://example.org/blog/entries/0-14
    
  IRI Templates containing tokens not understood by the client MUST
  be ignored.

Impacts

Notes

CategoryProposals