Catching Up with the Atom Publishing Protocol
The Atom Syndication Format is now also known as RFC 4287. Atom is an internet standard in the same way that little things like SMTP and HTTP -- also known as "email" and "the Web," respectively -- are internet standards. (If you're just now coming to terms with the Atom Syndication Format, check out Uche Ogbuji's Agile Web XML.com column this week for some practical advice and running code.)
Progress on the Atom Publishing Protocol (APP) has lagged a bit, in part because it relies so heavily on the format specification. Now that the format is done, work has progressed rapidly on the protocol.
Here is the general outline of how the protocol works; in particular, I'll point out design alternatives that the Working Group (WG) has considered and rejected and some of the reasoning behind those decisions. I'll also point out the lingering questions and open problems. Please be advised that this is just one person's viewpoint and that everything and anything can change before the WG puts its stamp of approval on a final version of the APP.
Here is an Atom Entry:
<entry xmlns="http://www.w3.org/2005/Atom"> <title>Atom-Powered Robots Run Amok</title> <link href="http://example.org/2003/12/13/atom03"/> <author> <name>John Doe</name> </author> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <summary>Some text.</summary> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml"> <p><i>[Update: The Atom draft is finished.]</i></p> </div> </content> </entry>
There are two things to notice about this Atom Entry. The first is that it is a completely valid Atom document. Yes, that's right, an Atom Entry is a valid Atom document in its own right. The format actually defines two kinds of documents: one with a document element of
atom:feed, the other with a document element of
The second thing to notice about this document is that it contains almost all of the information you would need to describe a weblog entry. You've got a title, author, summary, and the content. An Atom Entry is a good representation of a weblog entry, which shouldn't be terribly surprising, but it helps out a great deal when we go to design a RESTful web service for weblog editing. If you go back and read How to Create a REST Protocol, you see that we want to answer the four questions:
- What are the resources?
- What are the representations?
- What are the methods supported?
- What status codes can be returned?
The two major resources in this problem space are members and collections. There is a single member resource for each entry on your weblog. That member resource has an Atom Entry as its representation, and changing that Atom Entry representation is how the corresponding weblog entry is changed. The collection resource is a list of URIs of member resources. Put in our standard tabular form we get:
|Member||GET||Atom Entry||Retrieve the Atom representation of the entry.|
|Member||PUT||Atom Entry||Update the member resource with the Atom entry representation.|
|Member||DELETE||Atom Entry||Delete the member resource.|
|Collection||GET||Atom Feed||Retrieve a list of the members in the collection. May be a subset.|
|Collection||POST||Atom Entry||Create a new member resource with the given Atom Entry.|