Abstract
Adds flexibility to PaceOrderCollectionsByAppModified by allowing servers to expose the collection ordering (based on entry creation date/time, atom:updated or app:modified). Actually, this is not about configuration, but the server's behavior will likely be configurable, so it's rather about exposing the server's configuration.
Status
Open (ThomasBroyer)
Rationale
In "online mode", a client will always GET the entry before editing it, so the collection feed is only helpful in notifying new entries. Other orderings (by atom:updated, which is mainly designed for subscriptino/aggregation, or by app:modified, which is designed for sync'ing before going offline) would be here unnecessarily bandwidth consuming.
When synchronizing for "offline mode", such an ordering (by a pseudo "app:created") could be sufficient and the client would issue conditional GETs on every known entry to ensure it has the latest version, but this algorithm involves many round-trips and is very bandwidth consuming, and consumes more and more bandwidth whilst the number of entries grows, even if none of them has changed. Ordering by atom:updated does not solve the problem. Ordering by app:modified here is the best approach.
We need a configurable approach, where the server can be configured (or at least expose their implementation/configuration) depending on their use (optimized for online editing, optimized for offline editing, optimized for subscription --implies almost optimized for online editing--).
Proposal
Replace the second paragraph of section 9 in draft-atom-protocol-09 with:
The ordering of entries in the feed depends on the value of the "app:details-level" element (see section 10.3).
Add the following two new subsections in section 10:
10.3 The "app:details-level" element appDetailsLevel = element app:details-level { atomCommonAttributes, "creation" | "update" | "minor-change" } The "app:details-level" element MAY appear as a child of an "atom:feed" which represents a Collection. The "app:details-level" element, if it does appear in a feed, MUST only appear at most one time. The "app:details-level" element is considered foreign markup as defined in Section 6 of [RFC4287]. The "app:details-level" element's content MUST be either "creation", "update" or "minor-change". If the "app:details-level" is not provided, both clients and servers MUST behave as if it were present with a value of "update". The value "creation" means that entries in the Atom Feed are ordered by their "app:created" value (see section 10.4). Every entry in the feed MUST then have an "app:created" or "atom:published" element. The value "update" signifies that entries are ordered by their "atom:updated" value. The value "minor-change" indicates that entries are ordered by their "app:modified" value (see section 10.5). Both clients and servers MUST ignore foreign attributes present in the "app:details-level" element. 10.4 The "app:created" element appCreated = element app:created { atomDateConstruct } The "app:created" element MAY appear as a child of an "atom:entry" which is being created or updated via the Atom Publishing Protocol. The "app:created" element, if it does appear in an entry, MUST only appear at most one time. The "app:created" element is considered foreign markup as defined in Section 6 of [RFC4287]. The "app:created" element is a Date construct indicating the instant in time when the entry was created. If the "app:created" element is not provided and the entry contains an "atom:published" child element, clients MUST behave as if the "app:created" element were present with the same value as the "atom:published" element. If the "app:created" element is present in an Atom Entry sent to a server in the body of a POST or PUT request, the server MUST ignore it and its value. 10.5 the "app:modified" element appModified = element app:modified { atomDateConstruct } The "app:modified" element MAY appear as a child of an "atom:entry" which is being created or updated via the Atom Publishing Protocol. The "app:modified" element, if it does appear in an entry, MUST only appear at most one time. The "app:modified" element is considered foreign markup as defined in Section 6 of [RFC4287]. The "app:modified" element is a Date construct indicating the instant in time when the entry was last modified. The "app:modified" element is very similar to the Last-Modified HTTP header, thus, when included in an Atom Entry Document, its value SHOULD be the same as the one of the Last-Modified HTTP header applying to the entity. If the "app:modified" element is not present, clients MUST behave as if it were present with the same value as the "atom:updated" element. If the "app:modified" element is present in an Atom Entry sent to a server in the body of a POST or PUT request, the server MUST ignore it and its value.
In section 7.2.3 (the "app:collection" element), replace the second sentence with:
Two child elements are defined here for app:collection: app:accept and app:details-level.
Add the following new subsection to section 7.2:
7.2.5 The "app:details-level" element The app:collection element MAY contain one "app:details-level" element. The "app:details-level" element is defined in section 10.3. When used as a child of app:collection, its value is a hint for clients and SHOULD have the same value as the "app:details-element" present in the Atom Feed referenced by the app:collection's "href" attribute. Note that the "app:details-level" element within an app:collection does not override the actual media type returned within the Collection's Atom Feed.
Impacts
Example usage: clients could warn users that the server's configuration is not optimized for the use they want (online or offline mode), so they could fix the server's configuration (if they can, of course).
Notes
This Pace uses the "app" namespace rather than the "pub" one, as if PaceOneAppNamespaceOnly had been accepted, but it does not depend on it.