Blogging Roller

Here's the abstract of the talk I gave this morning at Tri-XML 2006:

Beyond blogging: Atom format and protocol. Like XML-RPC and SOAP before, feeds and publishing protocols were born in the blogopshere and quickly moved beyond blogging. Nowadays, web service providers are using RSS/Atom feeds and REST-based publishing protocols as lightweight alternatives to SOAP. And developers are finding new ways to combine web services from different sites into new applications, known as "mash-ups" in the lingo of Web 2.0. If you'd like to do the same, then attend this talk to learn about the new IETF Atom feed format (RFC-4287) and the soon-to-be-finalized Atom protocol, which together form a strong foundation for REST-based web services development.

Here's a rough outline of the talk:

• Introduction
• Beyond blogging
• Blogs hit the hit time
• The web is bloggy
• Atom as an alternative to WS-*
  
• Understanding feeds
• Birth of RSS
• RSS 1.0: the RDF fork
• The simple fork and RSS 2.0
  
• Atom: the standard
• Parsing feeds
• Fetching and parsing feeds
• Universal Feed Parser
• ROME utilities
• Windows RSS platform
• Serving feeds
• Approaches for generating and serving feeds
  
• Feed autodiscovery
• Styled feeds
  
• Atom protocol
• Compared to MetaWeblog
• REST based approach
• Introspection
• Collections
• Extending Atom
• Atom protocol in action
  
• Getting a service doc
• Getting collections
• Posting an entry
• Posting an image
• Demo: interacting with an Atom server via command-line
  

And here are the slides: TriXML2006-BeyondBlogging.pdf

Tags: topic:[Atom Publishing Protocol], topic:[Atom], topic:[APP], topic:[RSS], topic:[feeds]

Via The Aquarium I see that Mark Hadley's work on Web Application Description Language (WADL) is now a Sun Technical Report. WADL provides a way to describe a REST based web application or service so that tools can discover services, generate proxies, etc. As I understand it, WADL is to REST as WSDL is to SOAP.

There's also something new since the last time I looked at WADL. Mark has added a section on the Atom protocol and examples that show how to use a WADL file to replace an Atom introspection document. Looks like good stuff to me. If you need an introspection doc for your REST based web service, why not use WADL?

Via Google, I found that there's also a WADL presentation on-line.

I've used code from the excellent Pebble and Blojsom blog servers in the past (and given credit in the Roller CREDITS file). I'd love to be able to contribute back and now there's an opportunity to do that. So to Simon and David (or anybody else hacking those servers), if you want to get Atom protocol working in your server, the easiest way might be for you to bring in some code from Roller. I specifically designed our Atom protocol implementation to allow for sharing and to be free of Roller dependencies.

For example, here's how you'd do it for Pebble:

• Bring the classes from the package org.roller.presentation.atomapi into Pebble (except for RollerAtomHandler, you won't need that one).
  
• You'll also need to bring in the ROME and JDOM jars if you're not aleady using them.
  
• Implement the interface AtomHandler with calls to the Pebble backend, call it PebbleAtomHandler or something similar.
  
• Change one line of code in the AtomServlet method createAtomRequestHandler() to create your new PebbleAtomHandler instead of the Roller one.

And feel free to pepper me with questions along the way. I'd be happy to help and happy to make changes to make this sharing easier. I'm also considering the idea of an Atom Server Kit package in my Blogapps project (on second thought, ROME might be a better home).

When you're done, head over to the #atom channel on irc.freenode.net so we can do some interop testing with MatisseBlogger and other Atom protocol clients.

Joe Gregorio: APP, OpenSearch and Microformats. Get used to seeing them; those small pieces loosely joined are the future of web services.

Joe's talking about the new Lucene Web Services API, which is based on Atom protocol (APP), OpenSearch and Microformats. It's very cool to see the APP already applied outside of the realm of blogs.

I was planning on submitting Chapter 8 of RSS and Atom in Action to Manning today, but Atom protocol draft 7 has appeared. The changes look good and the only really significant one for me is the move from list templates, which allowed indexing into a collection, to next/previous paging as we had in draft 4. I'm going to revise my implementation, Chapter 8 and turn it in on Wednesday. Once that's done, I'll release Blogapps v0.1.

There's a new draft of the Atom Protocol available and I've already started working on updating my client (the BlogClient example from my upcoming book RSS and Atom in Action) and server (in the Roller sandbox) implementations. Surprisingly, the new spec doesn't look all that different from the previous one, so perhaps a weekend of work will do the trick.

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.