Now blogging at diego's weblog. See you over there!

a review of blogging APIs

As I was looking again at the space of remote-access APIs for weblog software (working on the XML-RPC Weblog Sync feature of clevercactus), I found that there was no side-by-side comparison of the main available APIs, or list of links of material to read. So here goes, in the hope that it will save time for others in the future. :)
Update: May 6 -- here is an introductory mini-howto I posted tonight on blogging APIs.
Another update: May 17 -- a follow up with a reply to some of Evan's comments, and some more discussion of the Blogger API 2.0.

As always, comments & corrections are most welcome!

Why an API?

First of all, why is an API necessary? The answer to this question is useful to me in evaluating how the APIs stack up against each other. In my view, the API should ideally provide programmatic access to all the functionality in the product. Weblog software is typically server side (even Radio, which is client-side, is actually running a web server in the client), and so the APIs are crucial to provide client-side access when needed. We don't live in an ideal world however, so at a minimum the API should provide:

  • The ability to create new posts (specifying not just content but dates, categories, etc.)
  • The ability to edit posts (again, including modifying not just content, but also dates, categories, etc.)
  • The ability to discover information about a user's accessible weblogs, information on how many posts there are, and so on.
  • The ability to retrieve any post, or a set of posts.

These are the main tests that an API has to pass to be truly useful as far as I'm concerned. Reading recent posts is not as important, IMO, since you can obtain those by reading the RSS feed of the blog anyway.

As a side note: these are my ideal features for a weblogging API for the usage I have in mind, which is letting cactus deal with weblogs as another data/source sink, which would in the end let weblogs replace emails in many situations, particularly for mailing lists. You would be able to create a full "backup" of your weblog in your local machine. You would be able to sync the contents of a space to a weblog, post new items, and read the feeds, creating a "roundtrip experience" on the client, while retaining the flexibility to use the weblog (both for reading and writing) for the situations when that's necessary. That is, let the user choose the appropriate tool for the appropriate time. Other applications will certainly have different needs, but I think that what I'm looking for is more or less the high end of what you'd want to do (at the moment--who knows where we'll be in six months!).

On to the APIs that are available.

What's out there: an overview

First, there seems to be a growing proliferation of blogging APIs. There are tons of open-source blogging software coming out, and some of them are also implementing their own remote access APIs. This only creates confusion and problems for developers.

One bright spot is that, so far, all APIs so far are being written on top of XML-RPC although I've seen whiffs of SOAP implementations. The fact that XML-RPC appears to be the de facto "standard" feels strange: usually it's high-level APIs which should be the standard, using any number of transports (e.g., XML-RPC, SOAP, BEEP, whatever). However, this is the situation at the moment, and it doesn't appear that there is a huge drive to change it for the foreseeable future. At a minimum, the fact that they are all being written in XML-RPC means that there's less transport headaches.

As far as what I reviewed, there seemed to be three main API contenders: the Blogger API v1.0, the MetaWeblog API, and the LiveJournal API (Those are the original source links; Userland maintains a main list of APIs here). Those three main API mirror three of the main blogging tools available: Blogger (now owned by Google as we all know), Radio and LiveJournal. MovableType, also very popular, only adds extensions on top of the Blogger and MetaWeblog APIs, as I mention below. The main developers of these APIs have been Evan (Blogger) and Dave (MetaWeblog). LiveJournal doesn't seem to identify with any particular authors per se. Ben & Mena, as developers of MovableType, also hold some sway in the community (I would think).

A developer preview of the Blogger API 2.0 was released last December, but the location given for the document now responds 'file not found' (which might be related to the Google purchase of Pyra and their subsequent adjustment of plans--I don't know). Strangely, the release was not mentioned in Evan's site, but it was mentioned in Dave's and Ben & Mena's, as well as in a zillion other blogs. Evan did respond to comments from Dave, who was asking for a move towards uniformity so that only one API has to be supported.

Of those three, the APIs to focus on are, IMO, Blogger 1.0 and MetaWeblog. All major blogging software implements both (with the notable exception of Blogger), and other, less known but still popular packages such as blojsom do as well. LiveJournal supports their own API and nothing else, and no one else seems to support the LiveJournal API. As far as I'm concerned, that makes it a closed system and so third in interest by a mile. Why would you write software that works with a single vendor? Microsoft might be able to pull that off, but that has to do more with monopolies and bulging bank accounts than with developers liking the idea. That said, the LiveJournal API is actually quite complete. If it was more widely supported, or if you really, really needed interaction with LiveJournal, it would be worth taking a second look. The Blogger 2.0 API is also out of the race for the simple reason that access to it is for developers only; it's still in flux, not deployed, and not widely supported. It seems that the API is moving closer to the functionality of the metaWeblog API, but as Ben commented there is still room for improvement and a lot of confusion built in. In particular, the new Blogger API, while being incompatible with 1.0, retains the method call names, something that's not, shall we say, ideal. Finally, MovableType has its own extensions to the APIs, but since it implements both Blogger and MetaWeblog I won't go into those. ManilaRPC is probably the oldest blogging API there is, but again since it applies only to Manila, and no one else supports it, I won't go into it in detail.

The comparison: Blogger API vs. MetaWeblog API

Before we get into the specifics, I can give one general impression: The Blogger API is a joke, and a bad one at that. This is probably to be expected since it's about two years old, but it's really disappointing to see that one of the most used weblog tools has such crappy developer support. The MetaWeblog API is much better, although it has one or two shortcomings as well (measured by the "tests" I mentioned above). The Blogger API has an incredibly simple-minded view of what a weblog post is, and it is completely, and I mean completely innapropriate for what people do with weblogs today, from posting images to using audio and so on.

To see why, look at the following lists of methods in each API:

Blogger API 1.0
blogger.newPost: Creates a new post.
blogger.editPost: Edits a given post.
blogger.getUsersBlogs: Returns information on all the blogs a given user is a member of.
blogger.getUserInfo: Authenticates a user and returns basic user information.
blogger.getTemplate: Obtains the main (or archive) index template of a given blog.
blogger.setTemplate: Sets the main (or archive) index template of a given blog.

MetaWeblog API
metaWeblog.newPost: Creates a new post.
metaWeblog.editPost: Edits a given post.
metaWeblog.getPost: Obtains a given post.
metaWeblog.newMediaObject: Uploads an image, movie, song, or other media object from a user's computer to the user's blog.

On the surface, the Blogger API appears to be more complete than MetaWeblog. This is not the case however, and there's a simple reason: the Blogger API considers the content of a post to be simply a string with no parameters whatsoever allowable. For example, when you editPost using the Blogger API, you can't change the date of the post, or do anything except modify its main text content. Yuck. Again, this comes from a simpleminded view of what a weblog post is, and one that is entirely innapropriate for the use most bloggers give to their blogging tools today.

The MetaWeblog API is, as I said, much, much better. It considers post content to be structures rather than simple strings, and the structures are elements of the item tag in RSS, so you can create essentially anything that you can read. Furthermore, it almost passes all of the "tests" I mentioned above. It doesn't have a way to query for a user's blogs or obtain information, and it doesn't let you edit templates etc. That said, all tools that I've seen implement the MetaWeblog API also implement the Blogger API, so you can use the getUserInfo call from Blogger and then use MetaWeblog for postings.

In summary: MetaWeblog API, good. Blogger API 1.0, bad. The Blogger API 2.0 apparently fixes many of these problems, let's hope it gets (re-)released soon.

In the end however, it's unlikely that any developer, particularly small developers, can choose one over the other. We will have to work with both for the foreseeable future, supporting other APIs like LiveJournal separately when necessary.

Final thoughts

A few things that will be important in the future, and are still missing: the ability to edit categories, and to specify things like RSS feed targets, among others. This of course falls into remote configuration of weblog software, rather than use of the software itself. This area hasn't been explored at all, but I think that as more people use blogging software the need to have simple, client-side configuration tools will grow.

Categories: technology
Posted by diego on May 3 2003 at 2:29 PM

Copyright © Diego Doval 2002-2011.
Powered by
Movable Type 4.37