UserPreferences

ProtocolFaq


Atom Publishing Protocol Developers' FAQ

Q: Do I need to use the Atom Publishing Protocol (AtomPub) to publish a weblog feed? Should I use AtomPub for in the weblog feed I offer to subscribers?

A: You can publish an Atom feed for your weblog subscribers to use without using the Atom Publishing Protocol at all. In fact, AtomPub does not really have any features that are useful for a read-only weblog feed. A blogging tool might allow you to use AtomPub to edit the weblog, but the editable AtomPub feed should usually be distinct from the read-only feed that your readers will subscribe to. In particular, usually your subscribers will want a feed (Atom Syndication) that is sorted and paged by the <atom:updated> date of each entry, whereas an AtomPub feed is supposed to be sorted and paged by the <app:edited> date. The AtomPub feed can also contain drafts (unpublished entries) that you do not want your weblog subscribers to see yet.

The Atom specifications that are immediately useful for public, read-only weblog feeds are [WWW]The Atom Syndication Format (RFC 4286) and the [WWW]Feed Paging and Archiving draft.

Q: What's the difference between a Feed and a Collection?

A: A Collection is expressed as a Feed. A Collection has two distinguishing characteristics: most importantly, you can create new entries by POSTing to it. You know this is true because an APP Service Document said so. Secondly, the specification says that the Entries SHOULD be ordered by the content of the app:edited element.

In REST terms, a collection is the resource and a feed is the representation.

Q: Can I create entries with PUT instead of POST?

A: Maybe, but that's not part of AtomPub. The central point of AtomPub is that you push some data at a Collection and the server comes back and tells you where it got stored.

Q: What error should I expect back from an AtomPub server if I PUT an updated Entry to a previously existing entry URI that has since been deleted?

A: It depends. If you did a conditional PUT with If-Match, then RFC2616 requires the response to be [WWW]412 Precondition Failed:

   If none of the entity tags match, or if "*" is given and no current
   entity exists, the server MUST NOT perform the requested method, and
   MUST return a 412 (Precondition Failed) response. This behavior is
   most useful when the client wants to prevent an updating method, such
   as PUT, from modifying a resource that has changed since the client
   last retrieved it.

If you're submitting something without an Etag to match against, you'll probably have a permissions problem. In HTTP, PUT can create resources. In APP, clients don't typically have control over the server's URI space, and that includes creating new "files" in "folders". You're likely to encounter [WWW]401 Unauhtorized or another 4xx code, since the server has probably authenticated you, but still isn't going to allow the client to create the resource there. Be sure to read the last sentence in the following quote:

The request requires user authentication. The response MUST include a
WWW-Authenticate header field (section 14.47) containing a challenge
applicable to the requested resource. The client MAY repeat the request 
with a suitable Authorization header field (section 14.8). If the request 
already included Authorization credentials, then the 401 response
indicates that authorization has been refused for those credentials...

This is quite different from the typical experience with 401, a loop where you try a password 3 times or more. Continuing with RFC2616 on 401:

...If the 401 response contains the same challenge as the prior response, 
and the user agent has already attempted authentication at least once, 
then the user SHOULD be presented the entity that was given in the 
response, since that entity might include relevant diagnostic 
information. HTTP access authentication is explained in "HTTP 
Authentication: Basic and Digest Access Authentication" .