Category: Atom Protocol
This page describes a mechanism for fetching subsets of a system's entries.
Blog/wiki systems that have a large number of entries need a way for clients to fetch subsets of those entries. It is not feasible, nor scalable, to only provide the entire set of entries at a time. It is also assumed that it is unreasonable to rely on the server to provide its own design of "chunks" of entries, or for the server to only provide (say) "the last N entries". It is assumed that historical access is required, and the client may have various presentation modes that require specific subsets.
Five parameters are required for a query of entries, all are optional:
Date field to constrain against. This will define one of N date fields (TBD). Examples: publish date, last modified date, etc
Start date. This will be an ISO 8601 date, possibly following a specific profile. (e.g. http://www.w3.org/TR/NOTE-datetime)
End date. Format similar to Start date.
Ordering of returned entries. One of: most-recent-first or oldest-first.
Maximum count of returned entries. An integer.
These five parameters can be marshalled to the server in a variety of ways. Several proposals have been given on the atom-protocol mailing list:
add Greg's Atom-Get-Partial example
Atom-Get-Partial: field=publish-date; start=20041001; end=20041013; order=asc; limit=20
This approach doesn't allow sorting, or specification of dates. It implies that entries are sorted by atom:updated. It's closest analogue is getRecentPosts() in other blogging APIs, but it's more flexible.
The concept of an Atom range is only meaningful for Atom Entry Collection resources.
Atom range specifications in the Atom Protocol apply to the sequence of Atom entries in Atom Entry Collections, sorted by atom:updated.
An Atom range operation MAY specify a single range of entries, or a set of ranges within a single Atom Entry Collection.
ranges-specifier = atom-ranges-specifier atom-ranges-specifier = atom-unit "=" atom-range-set atom-range-set = 1#( atom-range-spec | suffix-atom-range-spec ) atom-range-spec = first-entry-pos "-" [last-entry-pos] first-entry-pos = 1*DIGIT last-entry-pos = 1*DIGIT
The first-entry-pos value in an atom-range-spec gives the offset of the first entry in a range. The last-entry-pos value gives the offset of the last entry in the range; that is, the entry positions specified are inclusive. Offsets start at zero.
If the last-entry-pos value is present, it MUST be greater than or equal to the first-entry-pos in that atom-range-spec, or the atom-range-spec is syntactically invalid. The recipient of an atom-range-set that includes one or more syntactically invalid atom-range-spec values MUST ignore the header field that includes that atom-range-set.
If the last-entry-pos value is absent, or if the value is greater than or equal to the total number of entries in the Atom Entry Collection, last-entry-pos is taken to be equal to one less than total number of entries in the Collection.
By its choice of last-entry-pos, a client can limit the number of entries retrieved without knowing the number of entries in an Atom Entry Collection.
suffix-atom-range-spec = "-" suffix-length suffix-length = 1*DIGIT
The suffix-atom-range-spec form specifices the last N entries in an Atom Entry Collection. If the collection contains fewer members than the specified suffix-length, the entire collection is returned.
If a syntactically valid atom-range-set includes at least one atom-range-spec whose first-entry-pos is less than the total number of entries in the collection, or at least one suffix-atom-range-spec with a non-zero suffix-length, then the atom-range-set is satisfiable. Otherwise, the atom-range-set is unsatisfiable. If the atom-range-set is unsatisfiable, the server SHOULD return a response with a status of 416 (Requested range not satisfiable). Otherwise, the server SHOULD return a response with a status of 206 (Partial Content) containing the satisfiable ranges.
Examples of atom-ranges-specifier values (assuming an Atom Entry Collection with 10000 entries):
- The first 500 entries (offsets 0-499, inclusive): atom=0- 499 - The second 500 entries (offsets 500-999, inclusive): atom=500-999 - The last 500 entries (offsets 9500-9999, inclusive): atom=-500 - Or atom=9500- - The first and last entries only (entries 0 and 9999): atom=0-0,-1 - Several legal but not canonical specifications of the second 500 entries (offsets 500-999, inclusive): atom=500-600,601-999 atom=500-700,601-999
DASL Query Grammar
add Greg's grammar example
04:36:03 <devnull56> well i don't know the structure of the atom spec for these type of calls, but with the metaweblog api... 04:36:14 <devnull56> there's a getRecentPosts method that takes a certain number of posts 04:36:22 <devnull56> so 20 returns the last 20 posts 04:36:36 <devnull56> but there's no way to requests the last 20-30 posts 04:36:57 <devnull56> so if i wanted to create a client that let's you view the first 1-10 posts, then 11-20, then 21-30, etc 04:37:08 <devnull56> i would have to download posts 1-10, then 1-20, then 1-30 04:39:14 <jcgregorio> ah yes, the AtomAPI does have this, with the query parameters atom-begin-range and atom-end-range