Large Atom collections need to be accessible in small chunks. This proposal gives servers a way to slice the collection into subcollections, and it gives clients a way to dice those slices for their own needs. This method efficiently supports clients with or without persistent state.
See "Notes" at the bottom.
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 ("members" of the collection), 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 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." That document describes PART OF the state of the collection.
All the members of a collection have an "updated" property, and the collection is considered to be ordered by this property. A single collection document may not contain all of the members of a collection. If a collection document is the response of a non-partial GET request, and does not contain all of the members of a collection, then it will contain the URI of the next collection document which will contain more of the collection members. By traversing this list of collection documents a client can obtain all of the members of a collection. The @next attribute will not be present in the response to a partial GET request.
Below two usages are outlined for Atom Collections. They are here to highlight common idioms for interacting with a Collection Resource and not a normative interaction pattern.
The Atom Collection can be used by clients in two ways. In the first case the client has attached to a site for the first time and is doing an initial syncronization, that is, retrieving a list of all the members of the collections and possibly retrieving all the members of the collection also. The client can perform a non-partial GET on the collection resource and it will receive a collection document that either contains all the member of the collection, or the collection document root element <collection/> will contain a 'next' attribute pointing to the next collection document. By repeatedly following the 'next' attribute from document to document the client can find all the members of the collection.
In the second case the client has already done an initial sync, and now needs to re-sync, because the client was just restarted, or some time has passed since a re-sync, etc. The client does a partial GET on the collection document, supplying a Range header that begins from the last time the client sync'd to the current time. The collection document returned will contain only those members of the collection that have changed since the last time the client syncronized.
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 such element identifies a member of the collection. In some situations, a collection document may not contain every member of the collection itself.
Whether complete or partial, the members in a collection document MUST constitute a consecutive sequence of the collection's members, ordered by their "updated" properties. That is, a collection document MUST contain a contiguous subset of the members of the collection ordered by their 'updated' property.
3.X.2. Elements in a Collection Document
A collection document MAY contain zero or more <member> elements.
Each <member> element MUST include an "href" attribute identifying a URL of the member resource. The "href" URL of a member resource is an "EditURI" under the terms of section 2, and MUST respond to the same HTTP methods as such an EditURI.
Each <member> element MAY include an "hrefreadonly" attribute. This optional attribute identifies a URL which, on a GET request, responds equivalently to how the "href" URL would respond to the same request. Clients SHOULD NOT apply to this URL any HTTP methods that would be expected to modify the state of the resource (e.g. PUT, POST or DELETE). A PUT or POST request to this URL MAY NOT affect the underlying resource. If the "hrefreadonly" attribute is not given, its value defaults to the "href" value. If the "hrefreadonly" attribute is present, and its value is an empty string, then there is no URL that can be treated in the way such a value would be treated.
Clients SHOULD use the "href" value to manipulate the resource within the context of the APP itself. Clients SHOULD prefer the "hrefreadonly" value in any other context. For example, if the resource is an image, a client may replace the image data using a PUT on the "href" value, and may even display a preview of the image by fetching the "href" URI. But when creating a public, read-only reference to the same image resource, the client should use the "hrefreadonly" value. If the "hrefreadonly" value is an empty string, the client SHOULD NOT make public reference to the "href" value.
Each <member> element MUST include a "title" attribute, whose value is a human-readable name or description for the item. The values of "title" attributes are not required to be unique across all members of a collection.
Each <member> element MUST include an "updated" attribute, whose value is the 'updated' property of the collection member whose format MUST conform to the date-time BNF rule in [RFC3339].
3.X.3. Collection Requests
GET requests to a collection can be partial or non-partial depending on whether or not they include a Range header.
3.X.3.1. Range: Header
HTTP/1.1 allows a client to request that only part (a range of) the collection to be included within the response. HTTP/1.1 uses range units in the Range header field. A collection can be broken down into subranges according to the members 'updated' property.
If a Range: header is present in the request, its value explictly identifies the a time interval interval in which all the members 'updated' property must fall to be included in the response.
Range = "Range" ":" ranges-specifier
The value of the Range: 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.
ranges-specifier = updated-ranges-specifier updated-ranges-specifier = updated-unit "=" updated-range updated-unit = "updated" updated-range = [iso-date] "/" [iso-date]
The response to a collection request MUST be a collection document, all of whose <member> elements fall within the requested range. If no members fall in the requested range, the server MUST respond with a collection document containing no <member> elements.
3.X.3.2. Accept-Ranges: Header
The response to a non-partial GET request MUST include an Accept-Ranges header that indicates that the server accepts 'updated' range requests.
Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges acceptable-ranges = updated-unit ( 1#range-unit )
The containment model is not incompatible with the model of WebDAV, allowing special implementations to make extensions in that plane.