A set of requirements for Atom Collections supporting partial results and subcollections. An alternative to PaceDateRangeCollections.
provides date-range queries
has two URIs for a resource: one with "slash semantics," the other unrestricted but read-only
offers a way for collections to identify subcollections
provides NO reorderings
Requires date-range queries only if collections are returned partially
Requires full results on collections that don't have a date field.
Provides all the benefits of PaceDateRangeCollections.
Also allows collections to be hierarchically subdivided.
Add the following sections as children of "The Atom Publising Protocol Model," and "Functional Specification":
2.1 Atom Collections
An Atom collection is a set of items all of the same type, where the "type" may be, for example, Atom entry, category, template, "simple resource", or any other classification of web resource.
A collection may contain "subcollections." For purposes of this document, members of a subcollection are not considered members of the parent collection.
Each collection has a URI which is given in the introspection file. A GET on the collection URI MUST produce a collection document as defined in 3.X.1 Collection Document.
This document MAY include a <member> element for every item of the collection. Similary, the document MAY NOT include a <member> element for every item of the collection. In this case, it SHOULD contain an initial subsequence of the collection's member items, considered ordered by the value of their <updated> elements.
Some collection types do not require that their items have an <updated> property. Such collections MUST be returned in full.
3.X.1 Collection Document
A collection document is rooted by a <collection> element. A collection element may have any number of <member> elements as children; each resource element in the collection element identifies member of the collection.
Each <member> element MUST include an href attribute identifying the URI of the member resource. The URI of the member resource MUST include the collection URI as an initial substring, and MUST contain only one path segment after the collection URI. [[Path segments are separated by slash characters ('/').]] This restriction permits compatibility of the URI space with that of a WebDAV collection. The href URI of a member resource MUST respond to all the HTTP methods as required of an Atom resource under section 2. [[TBD: a section that specifies an Atom Resource as a thing that responds to requests in certain ways]]
A <sub> element in a <collection> document identifies a subcollection of the given collection. The <sub> element MUST have an href attribute whose value is the URI of the subcollection; this URI MUST include the parent collection's URI as an initial substring, and MUST contain only one path segment after the collection's URI.
A subcollection identified by the href attribute of a <sub> element is precisely a collection, as defined in sections 2.1 and 3.X.
3.X.2 Collection Date-Range Queries
A date-range query is a GET request on the URI of a collection (or subcollection), which includes an HTTP Range header. The value of the header should be a pair of ISO 8601 dates, separated by a slash character; either date may be optionally omitted, in which case the range is understood as stretching to infinity on that end.
atom-ranges-specifier = updated-ranges-specifier updated-ranges-specifier = updated-unit "=" updated-range-set updated-unit = "updated" updated-range-set = [iso-date] "/" [iso-date]
A date-range query identifies that subset of the (sub)collection members whose <updated> value falls within that range. If any items fall within that range, the server MUST respond with a partial collection document containing an initial subsequence of the items in that subset, when ordered by atom:updated. If no items fall within that range, the server MAY return an empty collection document, or it MAY return a [[xxx No Content response]].
The response to a date-range request MUST include a <sub> element for each subcollection of the requested collection that contains items falling within the requested range. The response MUST NOT include a <sub> element for any subcollection that does not contain members falling within the requested range.