At the Forge: Bloglines Web Services

More and more Web sites are offering machine-friendly versions of their services. Here's an example of a simple but useful service—updates on new Web site content.
Presenting the Bloglines API

Bloglines aggregates content from a large number of Weblogs and frequently updated news sources. Bloglines is happy to accept feeds in a variety of formats, including Atom and several versions of RSS. Indeed, Bloglines offers subscribers the choice of which feed to use, if more than one is available. The Bloglines software then archives that content, providing a search interface for interested users. Bloglines provides some relevance features, telling subscribers which additional Weblogs might interest them. Finally, Bloglines lets you look at other users' subscriptions; if you are interested in seeing which Weblogs interest me, you can review my profile and see my subscriptions.

For now at least, much of this functionality remains under wraps, available only through the Bloglines Web site. But three particular pieces of functionality now are available from the Bloglines Web services API:

  • Notifier: if you are a Bloglines subscriber and want to know when new content has arrived from one or more of the Weblogs to which you subscribe, now you can do it. This is the most established of the Bloglines Web services, and a number of tools for a number of operating systems and windowing toolkits rely on this interface to provide updates.

  • Sync API: allows you to retrieve information about a particular user's subscriptions, as well as the latest entries from each of those subscriptions. You can think of this as the data underlying the HTML that Bloglines generates for the main Weblog listing it provides.

  • Blogroll API: presents a way to retrieve and display a particular user's subscription list.

Notifier API

As I wrote above, Bloglines has decided to use REST for all of its Web services APIs. This means every request consists of a single URL, with all of the parameters and their values in the URL. Information is returned in whatever format the server deems appropriate. This stands in sharp contrast to SOAP, which specifies the name and type of each parameter and return value. A minor exception to this rule is that APIs requiring authentication expect the user name and password to arrive in HTTP Basic rather than in the URL itself. In the Bloglines universe, subscribers are identified by their e-mail addresses and user-selected passwords.

The easiest of the APIs to understand and use is the Notifier. To invoke the Notifier, simply go to the URL The response, while (incorrectly) tagged by the server as having a MIME type of text/html, contains a plain-text response of the format:


Notifiers can interpret the response as follows:

  • Normally, A indicates the number of unread Weblog entries in the user's subscription.

  • If the provided e-mail address is not registered with the system, then A contains -1.

  • If B isn't empty, it then contains a URL pointing to an upgrade page. The documentation doesn't say much about what it means to have an upgrade page. I assume that such a page is meant for people rather than programs, because it would be impossible or at least quite difficult to identify all of the programs that use the Notifier API and that are in need of an upgrade.

We easily could implement the client side of the Notifier API in any modern high-level language. But at the time of this writing, versions of Bloglines client libraries exist in Perl, Python and Ruby. I use the Perl version (on CPAN as WebService::Bloglines), but you may feel more comfortable rolling your own version, using a different version or both.

Here is a simple command-line program that prints “You have new blogs!” if Bloglines reports that new messages are waiting and “No new blogs” if I already have read everything:


use WebService::Bloglines;

my $username = '';
my $password = 'MYPASS';

my $bloglines = WebService::Bloglines->new(
                           username => $username,
                           password => $password);

my $unread_blogs = $bloglines->notify();

if ($unread_blogs)
print "You have '$unread_blogs' new blogs!\n ";
print "No new blogs.\n"

The number returned by $bloglines->notify() is the number of unread postings, not of unread Weblogs. If there are 15 unread messages from five Weblogs, $bloglines->notify() returns 15, not 5. Moreover, the number reflects the state of the internal Bloglines database. That is, if you click on the Keep New check box at the bottom of a Weblog entry, it is included in the count of new messages returned by $bloglines->notify().

If we enter an incorrect user name, our program exits with a fatal error and indicates that we gave it a bad user name. Giving a bad password has no consequences for the Notifier API, because that information is available publicly.