File Under: APIs

Using the Delicious API

Who’s that with the catchy URL that’s getting all the clicks?

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

  1. A script
  2. The API
  3. What else?


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:

 #!/usr/bin/php

 <?php

 $dusername = "festooningly";

 $dpassword = "leftalonetoolong";

 $api = "del.icio.us/api"

 

I read into a string variable the email message that Procmail passes to my script on standard input (stdin):


$fd = fopen("php://stdin", "r");

 $email = "";

 while (!feof($fd)) {

     $email .= fread($fd, 1024);

 }

 fclose($fd);

I break that variable into an array of individual lines …


 $lines = explode("n", $email);



… and I scan them, one at a time, looking for a line starting with “http:”, which I will assume is the URL we want to deliciousize:


 for ($i = 0 ; $i < count($lines) ; $i++) {

     if (preg_match("/^http:.*/", $lines[$i], $match)) {

         $bookmark = $match[0];

     }

 }

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:

 $bmarray = explode(" ", $bookmark, 2);

 $url = urlencode($bmarray[0]);

 $desc = urlencode($bmarray[1]);

The API

And now I’m ready for the del.icio.us API! I’m going to use the add method to add my bookmark.

$apicall =

 "http://$dusername:$dpassword@$api/posts/add?

 url=$url&description=$desc";

 $result = file($apicall);

And that’s it! Simply by requesting this URL from the del.icio.us server,

 http://username:password@del.icio.us/api/posts/add?url=http%3A%2F%2Fwebmonkey.com%2F&description=The%20Internet's%20Best%20Singles%20Hangout

I have told the site to add the URL and description to our account. It does so, and responds in XML:

 <?xml version='1.0' standalone='yes'?>

 <result code="done" />

That’s the response that tells us everything worked correctly – if there was an error of any kind, we get the slightly obscure

 <?xml version='1.0' standalone='yes'?>



 <result code="something went wrong" />

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.

Here’s that whole script in one piece:


 #!/usr/bin/php

 <?php

 $dusername = "festooningly";

 $dpassword = "leftalonetoolong";

 $api = "del.icio.us/api";

 $fd = fopen("php://stdin", "r");

 $email = "";

 while (!feof($fd)) {

     $email .= fread($fd, 1024);

 }

 fclose($fd);

 $lines = explode("n", $email);

 for ($i = 0 ; $i < count($lines) ; $i++) {

     if (preg_match("/^http:.*/", $lines[$i], $match)) {

         $bookmark = $match[0];

     }

 }



 $bmarray = explode(" ", $bookmark, 2);

 $url = urlencode($bmarray[0]);

 $desc = urlencode($bmarray[1]);

 $apicall =

 "http://$dusername:$dpassword@$api/posts/add?

 url=$url&description=$desc";

 $result = file($apicall);



 

What else?

Beyond posting bookmarks, the del.icio.us API lets you manipulate them in all sorts of ways, all with a simple URL and query string like the above.

 http://del.icio.us/api/posts/get?tag=davidbowie&date=2006-01-08 

returns an XML response of all entries tagged with “davidbowie” and dated January 8th, 2006.

 http://del.icio.us/api/posts/delete?url=http%3A%2F%2Fwebmonkey.com 

will delete the Webmonkey.com bookmark we posted above from the user’s collection of bookmarks.

 http://del.icio.us/api/tags/get 

returns a list of all the tags the user has ever used, and how many bookmarks are associated with each tag.

The documentation for all the API calls is here. I’ll be curious to see what you do with it! Keep an eye on del.icio.us/tag/del.icio.us too.