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:

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:

Custom Header

add Greg's Atom-Get-Partial example

[WWW]mailing list post

 Atom-Get-Partial: field=publish-date; start=20041001; end=20041013; order=asc; limit=20 

Custom range-specifier

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.

Atom Ranges

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-
      - The second 500 entries (offsets 500-999, inclusive):

      - The last 500 entries (offsets 9500-9999, inclusive):

      - 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):

DASL Query Grammar

add Greg's grammar example




[WWW]feature request:

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