Using the Delicious API

Why, it’s del.icio.us! No matter where you are on the “is-web-20.html Web 2.0” lash or backlash, the pervasive influence of this little bookmark aggregator can’t be denied. On the surface, it doesn’t do much more than the PHP tool I wrote back in 1999 to collect my bookmarks in a centralized location. So, you may ask (as I have asked myself repeatedly) why should I care, apart from the appe.al of spe.lli.ng ever.yth.ing like th.is? Well, the devil is in the details.

A few crucial features bear the responsibility for del.icio.us’s success. Most basically, it is a “social bookmarking” site – not social in the sense that you get to know whether your fellow users are Beck fans (although you might), but rather in that everybody’s bookmarks are in one big pool together. You can view your own or someone else’s. Or everybody’s.

Such a morass is ripe for confusion, which is where the next great innovation comes in: tagging. By now everybody uses tags to sort information, but their usefulness is easy to underestimate. Users can add any number of these descriptive keywords to their bookmarks. On del.icio.us, Webmonkey is tagged variously with web, webdesign, html, reference, css, programming, design, tutorial, tutorials, webdev, tips, resource, development – the list goes on. The proliferation of tags makes it easy to find links relevant to a particular subject: just go to http://del.icio.us/tag/webdev to find all links tagged with “webdev” – or triangulate by searching on the intersection of multiple tags: http://del.icio.us/tag/css+reference+webdev. Compared to the hierarchical limitations of putting things in folders, say, using intersecting tags is deliciously freeing.

Which brings us to excellent feature number three: a gloriously open malleability that sets del.icio.us far apart from its predecessors. Those URLs are an excellent example: notice how intuitively crafted they are? Say you want to find links tagged with “lithuania” – can you guess the URL for that dynamic page? I hope so, because I’m not going to tell you. But easy, predictable addressing is only the start of del.icio.us’s accessibility. The site offers a myriad ways of accessing its database, from HTML and RSS feeds, to JSON data, to browser integration of various types.

Let’s take a look at the public API, which offers flexible and easy access to del.icio.us.

Contents

A script

Del.icio.us’s delicious API offers methods for adding, reading, querying, and editing bookmarks, and makes it extremely easy to make del.icio.us part of any application. Let’s run through an example.

I’d like to be able to email a bookmark to a designated address – say, from my Treo, whose Web access is limited – and have that bookmark added to my del.icio.us account. Thanks to del.icio.us’s public API, it’s not hard to whip up a script that will do that for me. I’ll write it in PHP. Another language would do just as well; there’s even already a Python library for it. (Note that this is a PHP script that runs on the command line, not the more familiar Web-based type.)

I’ll just demonstrate a skeletal version, without the extra features I’d like: parsing of multiple URLs, the ability to tag, delete, rename, and sort bookmarks, the ability to receive bookmarks via return mail, and so much more. For reasons of space, I’m going to leave out all the error-checking that even a halfway decent programmer would include to vet the input for sanity, security, duplication, and so forth. Unfortunately, I’ve gotten to the point where I can’t do anything unless I intersperse it with a running narrative, like so:

First, on my Debian server, I need to configure Procmail to pass any messages sent to a particular address – say delicious@myserver.com – to my PHP script:

:0
* ^(To|Cc).*delicious@myserver.com
| php /usr/local/bin/delishmail

I create my PHP script at /usr/local/bin/delishmail, make it executable, and define some data that I need to access the API:

Arbitrarily, I’m going to decide that the email has to be formatted as “URL [space] description” – that is, the sole content of the email must be a line with an URL and its description, separated by exactly one space. (That makes the user’s job harder, but my job easier; on your own time, make things as complicated for yourself as you like!) I’ll leave out tags, notes, and the like for now – they’re an optional part of the API call I’m using. So a sample email to delicious@myserver.com might read:

http://webmonkey.com/ The Internet's Best Singles Hangout

My script has isolated that line, and it’s in my $url variable. Next I find the first space in the line, use that to split the line into its two components, URL and description, and encode them for posting:

The API is under development, so one can hope that error messages will be a little more perspicuous in future. Also note that that base URL of http://del.icio.us/api/ is prone to change, which is why I separated it out into a variable.