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.