UserPreferences

PaceServerCollectionSubsets


Abstract

Standardizes what items a server should return when it refuses to return an entire collection. In short: it should return the n most recently modified items.

Status

Draft

Rationale

In response to a request for a large collection, a server MAY return some subset of the collection. In that case, clients will want to know what they got so that they can form a follow-up query. This pace accomplishes that by specifying a standard subset that servers should return.

Furthermore, it is assumed that clients primarily wish to discover which individual items from the collection have been modified since the last time the client interacted with a given server. These are the items which the client needs to request in their entirety. This assumption informs the default subset that servers should return

Proposal

If a server receives a request for a collection (or part of a collection) that is too large to return in its entirety, the server MAY return a subset of the requested collection (or part). If the server returns a subset, it MUST reply with a status code of XXX, and the items returned MUST constitute a contiguous initial subsequence of the requested collection (or part), where the collection is ordered by the items' modification dates.

Impacts

This proposal works best if there is also a way for a client to request a subset of the collection, as specified by a range of modification dates. This way a client can iteratively request more subsets of the collection and can be sure that it always makes progress toward the entire collection.

This composes easily with PaceEntryQuery (in particular the "custom range header" section).

This proposal presumes a way of requesting and representing collections of Atom items. It works equally well for any type of Atom collection, whether the items be Entries, Templates, Categories, Principals, or any other.

Assumes that the server keeps track of a modification timestamp for all types of Atom items.

Notes

An appropriate response code should be picked when the server is returning less than what the client requested. 206 Partial Content?

Should the response code distinguish between client-specified subsets and server-specified subsets?


CategoryProposals