Blogging Roller

• Roller 1.2: I spent most of last week working on Roller 1.2. Part of that work was for the OpenSolaris launch. We used Roller 1.2's built-in "planet" aggregator to create the OpenSolaris blog, aggregating together about 150 blogs into one big blog with it's own newsfeed. I had to write a little custom code to load the list of blogs, because the aggregator's UI doesn't have a bulk-load capability yet. Later in the week I spent a couple of days on <a href= "http://opensource.atlassian.com/projects/roller/secure/ReleaseNote.jspa?projectId=10000&styleName=Html&version=10151"> fixing bugs, Javadocs and Velocidocs.

• Roller 1.3: We've started to talk a bit about a Roller 1.3 release to incorporate some theme management changes. We need to make it easier to manage themes and apply changes globally to all user's themes, but still allow power-users to tweak their page templates. Allen has put together a rough proposal for better theme management.

• Roller 2.0: I spent a couple of days on Roller 2.0 last week, still working on the data model and the new many-to-many relationship between weblogs and users. The OpenSolaris and Roller 1.2 contininued to put me further behind schedule, but I'm still shooting for group blogging done in August.

• Roller@Apache: Starting today, we're using the Apache incubator mailing lists for the Roller-dev and Roller-user lists, but I still haven't updated the wiki with subscribe and unsubscribe info.

• RSS and Atom in Action: Since the chapters are out of my hands, at this point all I can do is watch the Atom Protocol list. Chapter one may be coming back from copy-edit today.

Unlike the other RSS and Atom books that are hitting the shelves these days, RSS and Atom in Action is going to cover the Atom Publishing Protocol. So, I'm following the protocol development very closely. This blog entry is a summary of Atom as it stands today (based on Draft 04 released May 10, 2005). It's a follow up to my post earlier post Atom in a nutshell which explained Atom API 0.9.

Atom Publishing Protocol (a work in progress) is a new web services protocol for interacting with a blog, wiki or other type of content management system by simply sending XML over HTTP, no SOAP or XML-RPC required. Your code interacts with collections of web resources by using HTTP verbs GET, POST, PUT and DELETE as they are meant to be used. Here's how it works.

Discovering your workspaces and collections

To start out, you do an authenticated GET on a server's Atom URL to get a description of the services available to you. You get back an an Atom Services XML document that lists the workspaces and within each the collections available. A workspace could be a blog, a wiki namespace or content collection that you have access to via your username/password.

Each workspace can contain two types of collections: entries and resources. Eventually, the spec will probably allow for (at least) five types of collections: entries, categories, templates, users, and generic resources.

Here is an example of a services document XML for a blog user with access to two blogs "My Blog" and "Marketing Team Blog":

<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://purl.org/atom/app#">
     <workspace title="My Blog" > 
        <collection contents="entries" title="Blog Entries" 
            href="http://localhost:8080/roller/atom/myblog/entries" />
        <collection contents="generic" title="File Uploads" 
            href="http://localhost:8080/roller/atom/myblog/resources" />
     </workspace>
     <workspace title="Marketing Team Blog">
         <collection contents="entries" title="Blog Entries" 
             href="http://localhost:8080/roller/atom/marketingblog/entries" />
         <collection contents="generic" title="File Uploads" 
             href="http://localhost:8080/roller/atom/marketingblog/entries" />
     </workspace>
</service>

Working with collections

So, a workspace is a blog and a blog contains collections of things like entries, uploaded file resources, categories, etc. All of these collections are handled the same way and respond the same way to the HTTP verbs. All support paging, so the server can return a collection in easy to digest chunks. All support query by date, so you can filter collections by start and end date.

To get a collection, do a GET on it's URI (that's the collection's 'href' as listed in the services document).

The services document specifies a URI for each collection. If you do a GET on a collection URI, you'll get back an Atom Collection XML document that lists the first X number of members in the collection. If there are more than X members, then the document will include a next URI which you can use to get the next batch of members. You can also specify an HTTP Range header to restrict a collection to only those between specific start and end dates.

Here is an example of a the collection document XML you might receive by doing a GET on the Blog Entries collection from My Blog above.

<?xml version="1.0" encoding='utf-8'?>
<collection xmlns="http://purl.org/atom/app#"
   next="http://localhost:8080/roller/atom/myblog/entry/77088a1" >
   <member title="The Connells: Fun and Games"
         href="http://localhost:8080/roller/atom/myblog/entry/7700a0" 
         updated="2005-04-16T23:07:08-0400" />
   <member title="The Connells: Boylan Heights"
         href="http://localhost:8080/roller/atom/myblog/entry/7700c9" 
         updated="2005-04-15T23:06:09-0400" />
   <member title="The Connells: Gladiator"
         href="http://localhost:8080/roller/atom/myblog/entry/7700c8" 
         updated="2005-04-14T14:05:31-0400" />
</collection>

Each member in a collection document has a title and a URI. To get a member of a collection, you do a GET on the member's URI. To delete it you use DELETE. To update it you use PUT. Here's an example of the entry XML you might receive by doing a GET on the first member of the Blog Entries collection example above:

<entry xmlns="http://purl.org/atom/ns#">
  <title>The Connells: Fun and Games</title>
  <id>7700a0</id>
  <updated>2005-06-01T19:07:45Z</updated>
  <content type="html">
     Let me tear down into your heart
     Let me take a seat and stay awhile
     Let me have a half of your whole  
     Let me keep it for myself awhile  
  </content>
</entry>

To add a member to a collection, you simply POST the member to the collection's URI. If you're POSTing a new entry, send the XML for the entry (example entry XML shown below). If you're POSTing a file upload, then send the file.

That's it. Pretty simple huh?

What about authentication?

The Atom spec requires that a server support either HTTP digest authentication, which can be difficult for some bloggers to implement (depending on their ISP and web server), or CGI authentication, which can be a lot easier to implement (I believe WSSE qualifies as CGI authentication, and that's what my Atom implementation uses).

What about devices with limited HTTP support?

Some devices have crippled HTTP client capabilities. For example, some Java J2ME powered cell phones can't do an HTTP PUT or DELETE. If you can't do a PUT or a DELETE, you can use POST instead with a SOAP wrapper that specifies a Web-Method of PUT or DELETE. Atom servers are required to support SOAP POSTS and returning results in SOAP envelopes.

What about draft vs. published states for entries?

Still undecided. Some folks suggest using different collections for entries in different states (draft, approved, published, etc.). But it's more likely that a new element will be introduced in the Atom format to specify the state of an entry.

Summary

That's my summary of Atom protocol as it stands today. I think it's a great improvement over existing blog APIs in terms of features and design. And it's not very difficult to implement. I know because I'm almost done with my server and client implementations. I hope to release them shortly for review. The release will probably be a standalone release of Roller (the Atom server) and my BlogClient UI (the Atom client).

If you see some opportunities for improvement in the protocol, please join the Atom Protocol mailing list and help out. Last call for spec changes in now slated for October. And for the Atom experts out there: what did I get wrong? Leave a comment.

Time to test the power of positive thinking: this is the month that Atom Protocol settles down and becomes stable enough for me to finish up the book.

Some friends and I took a couple days of vacation in the North Carolina mountains. We were trapped in the house (pictured in the previous post) for most of the weekend, due to the extreme cold and a very icy road, but there's a full-sized pool table in the house, so we had no complaints.

I'm sorry if I have not returned your email. I was off-line for the weekend and since my return, I've been (mostly) ignoring my inbox and my newsreader so that I can finish Chapter 8: Publishing With Atom and some cool blogs.sun.com stuff that I can't talk about yet. I'm going to take a break this afternoon and tend to my mail and blog reading.

I spent most of the break working on the book and now it's time to get back to Roller. Bugs have been trickling in from blogs.sun.com. Plus, Matt and Rick over at Javalobby upgraded JRoller to Roller 1.0RC2 last week and that shook loose a couple of bugs. So, now there's a short list of bugs that should be fixed before Roller 1.0 final. Thanks to everybody who has helped out by reporting bugs.

We had nice quiet Thanksgiving and that's the way I like it. We travelled only about 30 miles, for dinner with my parents and my brother over in Chapel Hill. We had turkey, gravy, stuffing, rice, cranberry sauce, veggies, and of course, pumpkin pie and homemade ice cream. After lunch we took the traditional nice long walk around the neighborhood and this year the walk included the muddy path along Morgan Creek.

Now, we're back in Raleigh and I'm trying to get back into writing mode. I'm going to put the XML-RPC and Atom Protocol chapters on hold for a couple of days and work on revisions to the first 1/3 of the book. Reviews came back overwhelmingly positive, but that is just not good enough.

I've got a lot to be thankful for, but right now I'm most thankful for my wife's seemingly infinite patience -- that, and the fact that she is taking the boys away for a couple of days so that I can work in peace.