UserPreferences

PaceCollections


Abstract

Let dumb clients be dumb, let smart clients sync and traverse large result sets.

Status

Withdrawn

Rationale

PaceSliceAndDice is too limited, too rough on [WWW]naive clients, and uses XML containment to denote hierarchy when URIs will do a perfectly adequate job. Also, the world doesn't need another syndication format, so this proposal reuses the Atom Syndication Format for *every* collection representation, including "simple resources".

Problem Statement

The currently-deployed Atom Publishing Protocol is excellent for many clients, but is inadequate (and unextensible) for clients with more specialized requirements (cell phones, sophisticated apps such as Ecto and MarsEdit), and exacts a large penalty for "sync" operations. This proposal attempts to balance the currently-deployed protocol's cheerful Web coexistence while allowing for more sophisticated interaction when clients are APP-specific.

Proposal

The Atom Publishing Protocol Model

The Atom Publishing Protocol (APP) is an application-level protocol for publishing and editing Web resources, primarily for services that group resources with semantics that build on those specified in [RFC2616]. Examples include episodic resources such as weblogs or online journals, and entry-based resources such as Wikis.

The purpose of the Atom Publishing Protocol is to allow clients to discover and manipulate resources in manner consistent with the semantics of those applications. General-purpose authoring protocols such as FTP and WebDAV [RFC2518] do not present groups of resources in a manner consistent with these applications, where users often expect to see large numbers of resources grouped chronologically, rather than a wholy hierarchical "files and folders" approach. In addition, these protocols typically require the client application to choose the location of new resources, while Atom Publishing Protocol clients typically send a new resource to the server with the expectation that the server will choose an appropriate location for it. The APP builds on the WebDAV model, but does not require Level-1 or Level-2 WebDAV compliance.

Example Environment

Many implementations generate HTML documents, Atom Feed Documents, and other resources from a collection of resources controlled by the APP. The following diagram illustrates an example publishing scenario:

             +--------------+
             |   Browsers,  |
             | Feed clients,|
             |     etc.     |
             +--------------+
                    ^
                    |
                    | [HTTP GET...]
                    |
                    v
       +---------------------------+
       | +----------+ +----------+ |
       | |   HTML   | |   Atom   | |
       | | Document | |   Feed   | |
       | +----------+ +----------+ |
       |    ^                 ^    |
       |    |                 |    |
       | +-----------------------+ |
       | | Atom Entry Collection | | 
       | | +------------+        | | [HTTP Server]
       | | |Atom Entry  |        | |           
       | | +------------+        | |
       | | +------------+        | |
       | | |Atom Entry  |        | |       
       | | +------------+        | |
       | | +------------+        | |
       | | |Atom Entry  |        | |       
       | | +------------+        | |
       | | ...                   | |
       | +-----------------------+ |            
       +---------------------------+
                    ^
                    | 
                    | [HTTP GET,POST,PUT,DELETE...]
                    |
                    v
             +--------------+
             |     Atom     |
             |   Protocol   |
             |    Client    |
             +--------------+
 

Client and Server Interaction

Orientation

In order to discover the location of the collections defined by an APP service, the client must locate and request a Service Description document.

    Client                           Server 
       |                               |     
       |  1.) GET Service Description  |     
       |------------------------------>|     
       |                               |     
       |  2.) Service Description Doc  |     
       |<------------------------------|     
       |                               |
                

The client sends a GET request to the Service Description Resource.

The server responds with a Service Description Document containing the locations of collections provided by the service. The content of this document can vary based on aspects of the client request, including, but not limited to, authentication credentials.

Interacting with a Collection

Listing the Collection's Contents

Once the client has discovered the location of a collection, it can request a listing of the collection's membership. However, the collection might be extremely large, so clients can request a listing of a subset of the collection in one of two ways.

    Client                           Server 
       |                               |     
       |  1.) GET to Collection        |     
       |------------------------------>|     
       |                               |     
       |  2.) 200/206 Listing          |    
       |<------------------------------|     
       |                               |
Altering the Membership of a Collection

The client alters the membership of a collection by sending HTTP requests to its member entries, rather than the collection itself, except when it desires to add an entry to the collection. In that case, it sends a request to the collection. The following diagram shows a client adding, updating and then deleting an Atom Entry resource.

Create
    Client                           Server 
       |                               |     
       |  1.) POST Entry to Collection |     
       |------------------------------>|     
       |                               |     
       |  2.) 201 Created @ Location   |    
       |<------------------------------|     
       |                               |

The client sends an Atom Entry Document to the server via HTTP POST. The Request URI is that of the Atom Entry Collection.

The server responds with a response of "201 Created" and a "Location" header containing the URI of the newly-created Atom Entry Document. The entry is a member of the collection, so its URI is subordinate to the collection. Given a collection located at "http://example.com/foo/", acceptable member URIs include "http://example.com/foo/bar" and "http://example.com/foo/bar/baz".

Update

    Client                           Server 
       |                               |
       |  1.) GET or HEAD to Entry URI |     
       |------------------------------>|     
       |                               |     
       |  2.) 200 OK                   |    
       |<------------------------------|     
       |                               |
       |  3.) PUT to Entry URI         |     
       |------------------------------>|     
       |                               |     
       |  4.) 204 OK                   |    
       |<------------------------------|

If the client does not know the current state of the entry, it sends a GET (or HEAD) request to the Atom Entry's URI.

The server responds with an Atom Entry representation.

The client then PUTs an updated Atom Entry Document.

If the request is successful, the server responds with a 204.

Delete

    Client                           Server 
       |                               |
       |  1.) DELETE to Entry URI      |     
       |------------------------------>|     
       |                               |     
       |  2.) 204 No Content           |    
       |<------------------------------|     
       |                               |

The client sends a DELETE request to the Atom Entry's URI.

The server responds with a 204 No Content. Further GET requests to this URI will yield a 4xx response.

2.4 Additions to HTTP and WebDAV

The Atom Publishing Protocol specifies four major features not present in [RFC2616] and [RFC2518].

Atom Collections

Web Collections are defined by WebDAV [RFC2518], but Atom collections MAY NOT meet the compliance requirements enumerated by that document. However, [RFC2518] does allow "Non-Compliant Collections", meaning resources can assert that they are collections without meeting any level of WebDAV compliance. Therefore, Atom collections are WebDAV collections, but are not required to respond to any HTTP method specified in [RFC2518], including PROPFIND, COPY, and LOCK.

All Atom collections are Ordered Collections [RFC3648].

Representing Collections

Though the member resources of a collection could be pretty much anything, this specification uses one representation when listing the members of a collection: the Atom Entry. This specification defines its own root element for the listing, rather than reusing Atom Feed Documents.

<pub:collection xmlns="..."  xmlns:pub="...">
...
<entry>
  <title>foo</title>
  <pub:edit href="http://www.example.org/e4/c234/item/01"/>
  <link href="http://www.example.org/public/item/01"/>
  <id>http://www.example.org/e4/c234/item/01</id>
  <updated>2004-12-17T00:00:00Z</updated>
</entry>
...
</pub:collection>

In an Atom Collection document, a link element with a relation of "alternate" conveys the location of a derived resource, while the pub:edit element conveys the location where the resource may be edited.

GET Requests

Servers respond to GET requests with server-determined subset of the collection. For example, it could respond with an APP collection document containing the tem most recently modified resources.

Specialized GET Requests

The SEARCH method is defined later in this document; its role is a safe request with a body. Result sets from SEARCH requests can be segmented using Atom ranges. This specification defines the following types of query:

SEARCH /news/
Range: atom=-4
Accept: application/atom+xml

<query xmlns="...">
<end-date>...</end-date>
<begin-date>...</begin-date>
<view>full</view>
</query>

HTTP/1.1 206 Partial content
Date: Wed, 15 Nov 1995 06:25:24 GMT
Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
Content-Range: atom 47018-47021/47022
Content-Length: ...
Content-Type: application/atom+xml

<pub:collection ...>
...
[4 entries]
...
</pub:collection>

SEARCH requests MAY include a <begin-date>, <end-date>, or both, in order to return a listing of resources updated in a given date range. If the message has no body, the request is considered to be equivalent to a request containing an <end-date> element with the current time. Clients may traverse the result set by including an Atom Range.

The <view> element allows clients to select the type amount of information they would like to receive about each entry. This specification defines two values for this field: "full" and "brief". If the value is "full", the contents of Atom entries SHOULD be identical to their representations were a GET request sent to the URI in conveyed in the pub:edit element. If the value is "brief", the entry is only required to contain the elements required by the Atom Syndication Format, and the pub:edit element. Servers MAY include additional elements, but should be aware that clients requesting brief views could require small representations for a variety of reasons.

Atom Ranges

...

The 'atom' ranges-specifier

The concept of an Atom range is only meaningful for Atom Collection resources.

Atom range specifications in the Atom Protocol apply to the sequence of resources in Atom Collection representations, sorted by the ordering specified for a given collection type.

An Atom range operation MAY specify a single range of non-collection member resources in an Atom Collection.

       ranges-specifier = atom-ranges-specifier
       atom-ranges-specifier = atom-unit "=" atom-range-set
       atom-range-set  = ( 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 resource in a range. The last-entry-pos value gives the offset of the last resource 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 resources in the Atom Collection representation, 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 resource elements retrieved without knowing the number of resources in an Atom Collection representation.

       suffix-atom-range-spec = "-" suffix-length
       suffix-length = 1*DIGIT

The suffix-atom-range-spec form specifices the last N resources in an Atom Collection representation. If the collection contains fewer members than the specified suffix-length, the entire collection representation is returned.

If a syntactically valid atom-range-set includes an atom-range-spec whose first-entry-pos is less than the total number of resources in the collection, or a 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 Collection with 10000 resources):

      - The first 500 resources (offsets 0-499, inclusive):  atom=0-
        499
 
      - The second 500 resources (offsets 500-999, inclusive):
        atom=500-999

      - The last 500 resources (offsets 9500-9999, inclusive):
        atom=-500

      - Or atom=9500-

Notes


CategoryProposals