UserPreferences

PaceProtocolResponseFormat


Rationale

The "member" syntax is bloat, but changes in addition to the response format are hard to digest simultaneously. Paging and duplicate POSTs are not handled by this proposal, but mechanisms for dealing with them would be straightforward to add in a separate proposal. There is also room to add annotation.

Proposal

Drop sections 4,5,6, and 7 in full. Replace as follows:

The Atom Pubishing Protocol Model

The Atom Publishing Protocol operates on collections of Web resources. All collections support the same basic interactions, as do the resources within the collections. The patterns of interaction are based on the common HTTP verbs.

Collections

The APP groups resources into "Collections", which are analogous to the "folders" or "directories" found in many file systems.

Discovery

To discover the location of the collections exposed by an APP service, the client locates and requests an Introspection Document (Section 8).

   Client                      Server
   |                                |
   |  1.) GET Introspection         |
   |------------------------------->|
   |                                |
   |  2.) Introspection Doc         |
   |<-------------------------------|
   |                                |
  1. The client sends a GET request to the Service Description Resource.

  2. The server responds with an Introspection 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.

Listing

Once the client has discovered the location of a collection, it can request a listing of the collection's membership. However, collections might be extremely large, so servers are likely to list a small subset of the collection by default.

   Client                      Server
   |                                |
   |  1.) GET to Collection URI     |
   |------------------------------->|
   |                                |
   |  2.) 200 OK, Atom Feed Doc     |
   |<-------------------------------|
   |                                |
  1. The client sends a GET request to the Collection's URI.

  2. The server responds with an Atom Feed Document containing a full or partial listing of the collection's membership.

Authoring

After locating a collection, a client can add entries by sending a request to the collection; other changes are accomplished by sending HTTP requests to its member resources.

Create

   Client                      Server
   |                                |
   |  1.) POST to Collection URI    |
   |------------------------------->|
   |                                |
   |  2.) 201 Created @ Location    |
   |<-------------------------------|
   |                                |
  1. The client sends a representation of a member to the server via HTTP POST. The Request URI is that of the Collection.

  2. The server responds with a response of "201 Created" and a "Location" header containing the URI of the newly-created resource.

Read

   Client                      Server
   |                                |
   |  1.) GET or HEAD to Member URI |
   |------------------------------->|
   |                                |
   |  2.) 200 OK                    |
   |<-------------------------------|
   |                                |
  1. The client sends a GET (or HEAD) request to the member's URI.

  2. The server responds with an appropriate representation.

Update

   Client                      Server
   |                                |
   |  1.) PUT to Member URI         |
   |------------------------------->|
   |                                |
   |  2.) 200 OK                    |
   |<-------------------------------|
  1. The client PUTs an updated representation of the member's new state to the member's URI.

  2. The server responds with a representation of the member's new state.

Delete

   Client                      Server
   |                                |
   |  1.) DELETE to Member URI      |
   |------------------------------->|
   |                                |
   |  2.) 204 No Content            |
   |<-------------------------------|
   |                                |
  1. The client sends a DELETE request to the member's URI.

  2. The server responds with successful status code.

Success and Failure

HTTP defines classes of response. HTTP status codes of the form 2xx signal that a request was successful. HTTP status codes of the form 4xx or 5xx signal that an error has occurred, and the request has failed. Consult the HTTP specification for more detailed definitions of each status code.

Collections

An Atom Collection is a set of related resources represented by one or more Atom Feed documents [AtomFormat]. Atom Collections are ordered the date their members were updated, with the most recently updated member appearing first.

GET

Collections can contain extremely large numbers of resources. A naive client such as a web spider or web browser would be overwhelmed if the response to a GET reflected the full membership of the collection, and the server would waste large amounts of bandwidth and processing time on clients unable to handle the response. As a result, responses to a simple GET request represent a server-determined subset of the collection's membership.

An example collection feed:

<feed xmlns="http://www.w3.org/2005/Atom"   
      xmlns:pub="http://purl.org/atom/app#">
  <title>My Posts1</title>
  <id>urn:uuid:ce61592c-14e2-4557-978e-dfbd444aefa6</id>
  <updated>2005-12-21T04:11:00-08:00</updated>
  <!-- 0 or more atom:entry elements follow -->
  <entry>
   <title type="text">title 25</title>
   <updated>2005-12-21T04:11:00-08:00</updated>
   <author>
     <name>Foo</name>
   </author>
   <id>urn:uuid:941e12b4-6eeb-4753-959d-0cbc51875387</id>
   <pub:edit href="./entry7.atom"/>
   <link href="/permalink7.html" />
  </entry>
  ...
</feed>

Each member is represented by an Atom Entry, but those entries are not an editable representation of the entry. To retreive the source representation of the entry, clients send a GET request to the URI found in each entry's pub:edit element (see Section XX). Derived resources are located by examining an entry's atom:link elements.

POST

In addition to GET, a Collection Resource also accepts POST requests. The client POSTs a representation of the desired resource to the Collection Resource. Note that some collections only allow members of a specific media-type and a POST MAY generate a response with a status code of 415 ("Unsupported Media Type").

In the case of a successful creation, the status code MUST be 201 ("Created").

Example request creating a resource in a collection.

POST /collection HTTP/1.1
Host: example.org
User-Agent: Cosimo/1.0
Content-Type: application/atom+xml
Content-Length: nnnn

...data...

Example response

HTTP/1.1 201 Created
Date: Mon, 21 Mar 2005 19:20:19 GMT
Server: CountBasic/2.0
ETag: "4c083-268-423f1dc6"
Location: http://example.org/stuff/foo13241234.atom

Entry Collection

Entry Collections are Collections that restrict their membership to Atom entries. The entries are edited by sending HTTP requests to the URI found in an individual entry's pub:edit element. Servers can determine the processing necessary to interpret a request by examining the request's HTTP method.

x.1 The pub:edit Element

The pub:edit element has one attribute, 'href'. The value of this attribute is an IRI reference interpreted relative to xml:base.

Role of Atom Entry Elements During Editing

The elements of an Atom Entry Document are either a 'Writable Element' or a 'Round Trip Element'.

Writable Element - An element of an Atom Entry whose value is editable by the client and not enforced by the server.

Round Trip Element - An element of an Atom Entry whose value is enforced by the server and not editable by the client.

That categorization will determine the elements' disposition during editing.

Atom Entry Element Property
atom:author Writable
atom:category Writable
atom:content Writable
atom:contributor Writable
atom:id Round Trip
atom:link Writable
atom:published Writable
atom:source Writable
atom:summary Writable
atom:title Writable
atom:updated Round Trip

Media Collections

Media Collections are Collections that do not have uniform restrictions on the representations of the member resources. For example, they micht contain JPEG images, TXT documents, MPEG movies, and any other type of resource the server allows.

GET

Media collections return an Atom feed much like entry collections, but with a few additions. The listing MUST also contain an atom:content element with a 'src' attribute pointing to the media resource. This URI can be used to edit the uploaded media resource, using PUT and DELETE.

Such entries MAY contain pub:edit elements used to edit the entry metadata. As with other collection members, derived resources can be located by inspecting an entry's atom:link elements.

An example Media Collection feed:

<feed xmlns="http://www.w3.org/2005/Atom"   
      xmlns:pub="http://purl.org/atom/app#">
  <title>My Posts1</title>
  <author>
    <name>Foo</name>
  </author>
  <id>urn:uuid:ce61592c-14e2-4557-978e-dfbd444aefa6</id>
  <updated>2005-12-21T04:11:00-08:00</updated>
  <!-- 0 or more atom:entry elements follow -->
  <entry>
   <title type="text">title 25</title>
   <updated>2005-12-21T04:11:00-08:00</updated>
   <id>urn:uuid:941e12b4-6eeb-4753-959d-0cbc51875387</id>
   <link href="/permalink7.html" type="text/html" />
   <link href="/stuff/public/beach.jpg" type="image/jpg" 
         title="Low res public version" />
   <summary>this was awesome</summary>
   <content src="http://example.org/asdf.jpg" />
  </entry>
  ...
</feed>

The Atom Syndication Format requires that each such entry contain an atom:title and atom:summary element. This requirement can be challenging to meet without requiring users to enter tedious metadata, but servers SHOULD attempt to provide textual data about the resource in the interests of accessibility. The atom:title element will likely be provided by the client, as way for users to associate their local resources with those they have uploaded to the server (see POST below).

POST

To create media resources, clients POST the resource to the Media Collection's URI. Clients SHOULD provide a 'Title' request header to provide the server with a short string identifying the resource to users. Clients MAY include a 'Content-Description' header providing a more complete description of the content. In addition, servers MAY inspect the POSTed entity for additional metadata to be exposed in an atom:entry when listed in a Media Collection. For example, the server might inspect a JPEG file for EXIF headers containing creator data.

POST /collection HTTP/1.1
Host: example.org
User-Agent: Cosimo/1.0
Content-Type: image/jpg
Content-Length: nnnn
Title: A Trip to the beach
Content-Description: It was so fun.

...binary data...

Example response

HTTP/1.1 201 Created
Date: Mon, 21 Mar 2005 19:20:19 GMT
Server: CountBasic/2.0
ETag: "4c083-268-423f1dc6"
Location: http://example.org/stuff/beach.jpg

Notes

See also: PaceProtocolPaging