A simple set of requirements around Atom Collections that supports partial results.
provides date-range queries
has two URIs for a resource: one with "slash semantics," the other unrestricted but read-only
provides NO reorderings or subcollections
Requires date-range queries only if collections are returned partially
Requires full results on collections that don't have a date field.
Alternative proposals include PaceRangesAndSubsets
A slash-separated URI hierarchy offers a compatibility with WebDAV for implementations that find that useful.
An alternate read-only URI allows servers to determine a network-savvy location for mass consumption of the resource.
Alternate orderings have gotten little support.
Collections that don't have a date field, such as users, are likely to be in less need of partial responses.
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.
Each collection has a URI. A GET on the collection URI MUST produce an collection document as defined in Collection Document. This document MAY contain a <member> element for every item of the collection. Alternatively, this document MAY contain an initial subsequence of the items of the collection, 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.
If the document retrieved at the collection URI does not contain all items belonging to the collection, the response code MUST be [[some partial-response code]]. In this case, the server MUST support Date-Range Queries.
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. [[make a section that specifies an Atom Resource as a thing that responds to requests in certain ways]]
Each <member> element MUST include a readonlyhref attribute whose value is a URI at which the member resource can be fetched; no restriction is placed on the value of the readonlyhref URI. The readonlyhref URI MUST respond to a GET request, but no other methods are required by this specification. [[Maybe: the content of a GET response at the readonlyhref URI MUST be the same as that of a GET response at the href URI??]]
X.Y.2 Date-Range Queries
A date-range query is a GET request to the URI of a collection, which includes an HTTP Modified-Range: header. The value of the header should be a pair of ISO 8601 dates, separated by a slash character; either date may optionally be omitted, in which case the range is understood as stretching to infinity on that end.
modified-range-header ::= optional-iso-date '/' optional-iso-date
optional-iso-date ::= iso-date | empty-string
A date-range query identifies that subset of the collection items whose atom: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]].
Category collections could be large. If we require a date field on collections, then clients could fetch just those categories that have changed since a given date. Without a date field, clients might be forced to get the entire category collection each time it talks to a server.