At the Forge - Bloglines Web Services, Continued

Although some Web community sites get evil and lock in the users, Bloglines takes an open approach and lets you point your own scripts at its Web services API. Drop in and catch up with your favorite blogs.

If you are interested in preserving the subscription hierarchy the interface gives users, you might want to examine the folders function, rather than the feed function used in Listing 1. Although feed returns a flat list of subscriptions, folders keeps things organized as they exist on the Bloglines site.

Getting Items within a Subscription

Now that we know how to retrieve the subscription IDs associated with a particular Bloglines user, we can retrieve individual items associated with a particular subscription ID. For example, Listing 2 is a short program that retrieves all of a user's subscriptions and then displays all of the newly updated items for each. The output is in plain-text format, not in HTML, which means the displayed link is not clickable. But, it would not be particularly difficult to run such a program in a cron job and dump its output into an HTML file, thereby giving an up-to-the-minute personalized list of feeds. Of course, Bloglines provides such a service at no cost whenever you might want to check its Web site. So, although such a program is an interesting use of the Bloglines Web services, it doesn't have a compelling use outside of those services.

One of the clever things that Bloglines has done in its Web services definition is to use HTTP return codes to indicate errors and unusual circumstances. For example, the 200 (OK) response code indicates that new items may be read and that getitems($subId) contains one or more such data structures. The 304 (unchanged) response code, which normally indicates a page of HTML has not changed since it last was requested, here has a slightly different function; it indicates that a particular subscriber already has seen all of the available items for this subscription. Other response codes (401, 403 and 410) indicate authentication errors and probably mean that the requesting user has made a mistake in typing the Bloglines user name, password or both.

Unfortunately, Perl's handling of such response codes is less than optimal. In order to handle them, we must invoke $bloglines->getitems() inside of an eval block and check for a non-empty value of $@ immediately after the eval. If $@ is empty, we can assume that we received a 200 (OK) HTTP response code and there are new items to read. But if it contains a value, we then can rewrite the output message, as we did in Listing 2 . If we fail to trap this method call within an eval block, however, our program will die with a fatal runtime error the first time we receive anything other than a 200 response code.

Finally, two optional parameters make the Bloglines functionality complete. The first, known as n, is a simple true-or-false (1 or 0) value that tells Bloglines if it should update the already-seen bit for the articles it is sending to you. Normally, when a user is viewing Weblog postings with the Web interface, this is set to 1, meaning you do not see any already-seen articles a second time. Perhaps because they knew the Web services API currently supplements other news aggregation applications, Bloglines wisely changed the default to 0 in this API.

The second optional parameter, known as d, tells Bloglines the first date from which you would like to download a particular site's postings. The value is in UNIX time format, meaning that you send the number of seconds since January 1, 1970. This number is readily available with the time function in most major languages, and it allows you to indicate with great precision exactly how far back you want to delve into a particular site's history, as stored by Bloglines.