Synchronize Delicious and WordPress: Delicious API

Third part of the serie on Delicious. In this post, we will look at the API of this tool, all resources available for developers to manage data, and make links between Delicious platform, and WordPress.
It’s also time to check if the version 2.0 of Delicious brings some new functionalities.

Globally, Delicious provides 3 kinds of tools:

  • Badges: small gadgets displaying links such as Bookmark this with logos,
  • Scripts (javascript) to display lists of tags, lists of bookmarks,
  • API allowing to access to the Delicious database.

Badges

To summarize, badges are made to display logo or some slogan (in sidebar for example), in order to

  • Record the current page to Delicious,
  • Display a link to your bookmarks.

There is no change between the previous and the current version of Delicious. The site provides HTML or Javascript code in order display Save button, or a kind of Delicious identity card.

Delicious network badge
Delicious network badge

In both cases, the code can be directly copy/pasted into a template of a WordPress theme, or can be embedded into a widget, for example.
You have to take care about response time: during my tests, I saw some bad response time of the Javascript scripts. Use this scripts can generate some slowdown.

Display Delicious information into WordPress

Once again, nothing new. Two lists are provided: the linkroll and the tagroll. The first list gives a list of our last bookmarks, and the second one is a tags cloud.
In both cases, you can add parameters to the scripts, and Delicious provides a simple small interface for that.

RSS Feeds

One of the API provided by Delicious use RSS feeds. Delicious uses this feeds to publish the last changes occurring in its database. The syntax is simple:

  • http://feeds.delicious.com/v2/rss/recent gives the last added links,
  • http://feeds.delicious.com/v2/rss/{utilisateur}/{tag} provides links of a specified user and tag,

The query results are in XML, using the same syntax than RSS feeds.
The following code shows information available:

1
2
3
4
5
6
7
8
9
10
11
12
13
    <item>
      <title>TemplateLite.com</title>
      <pubDate>Wed, 04 Mar 2009 14:11:02 +0000</pubDate>
      <guid isPermaLink="false">http://delicious.com/url/022b7338a028b415b0140b6b4da54167#georjon</guid>
      <link>http://www.templatelite.com/</link>
      <dc:creator><![CDATA[georjon]]></dc:creator>
      <comments>http://delicious.com/url/022b7338a028b415b0140b6b4da54167</comments>
      <wfw:commentRss>http://feeds.delicious.com/v2/rss/url/022b7338a028b415b0140b6b4da54167</wfw:commentRss>
      <source url="http://feeds.delicious.com/v2/rss/georjon">georjon's bookmarks</source>
      <description>Professional Wordpress Themes - Free and Quality Wordpress Templates</description>
      <category domain="http://delicious.com/georjon/">wordpress</category>
      <category domain="http://delicious.com/georjon/">themes-templates</category>
    </item>

Advantages

  • The format is standard (XML / RSS),
  • we have all information available for links,
  • WordPress has tools to manage the RSS feeds (class MagPieRSS in the file wp-includes/rss.php).

Disadvantages

  • This method doesn’t allow to keep and store ALL links, because the number of links returned by queries is limited (between 1 and 100). It would be difficult to use this method in order to backup Delicious database into the WordPress blogroll,
  • This API is NOT useful to synchronize two links databases. For example, queries allow us to get the last n bookmarks, but not the bookmarks since a specified date. So an incremental synchronization is possible, but with some risks.

Some comments about badges

Use directly Javascript scripts can generate some latency or slowdown. A work-around should be to use the RSS API, and store collected data into a cache. The query http://feeds.delicious.com/v2/{format}/userinfo/{username} gives all data required to display network badges.

API HTTP

The second API available uses http queries.

Queries

Delicious gives us a set of addresses, in order to query the bookmarks database. The structure is always the same:

https://api.del.icio.us/v1/{object type}/{action}

For example, to get the list of last links, the command will be:

https://api.del.icio.us/v1/posts/get?

If we use this address with our browser, it will ask us a user name and a password. No so automatic! To avoid these questions, the full syntax is:

https://{username}:{password}@api.del.icio.us/v1/{object type}/{action}?{options}

We can also use parameters to specify dates, or filter the results.

It would be useless to list of the available queries. The following are just examples:

  • https://api.del.icio.us/v1/posts/all? allows us to get all bookmarks,
  • https://api.del.icio.us/v1/posts/all?tag=wordpress gets all links with tag containing the word « WordPress »,
  • https://api.del.icio.us/v1/tags/get gives the list of tags, with number of occurrence of each,
  • https://api.del.icio.us/v1/tags/bundles/all? sends list of bundles, with associated tags.

Results of queries

The results of the queries are in XML format. The following example is coming from the Delicious’ documentation:

$ curl https://user:passwd@api.del.icio.us/v1/posts/recent
 
<posts tag="" user="user">
  <post href="http://www.weather.com/" description="weather.com"
  hash="6cfedbe75f413c56b6ce79e6fa102aba" tag="weather reference"
  time="2005-11-29T20:30:47Z" />
    ...
  <post href="http://www.nytimes.com/"
  description="The New York Times - Breaking News, World News & Multimedia"
  extended="requires login" hash="ca1e6357399774951eed4628d69eb84b"
  tag="news media" time="2005-11-29T20:30:05Z" />
</posts>

Some comments about this example:

  • The time values have always the same format: yyyy-mm-ddThh:ii:ssZ. The time is UTC timezone, that is very useful, because we don’t have to take care about where we are,
  • The field hash is a kind of unique ID. It is used to detect the last modifications,
  • No query allows to get direct links between bundles and bookmarks. We have to use tags for that.

Advantages

  • Query are simple, and the result is XML. If you work with PHP 5, the result can be easily analyzed with just two or three lines of code,
  • The API gives access to the whole Delicious database: bookmarks, tags, bundles, network, …,
  • We can query, but also modify the database.

Disadvantages

  • To avoid that queries overload Delicious servers, there are some security functions. But these protections are a little bit too strong. If you send two or three queries, with less than few seconds between them, the service will send you a beautiful message such as « Service not available, try later ». I understand the reasons of these security functions, but I think there are too sensitive.
  • Queries allowing to detect all updates, give us lists of added or modified bookmarks, but not deleted bookmarks. A true « two-ways » synchronization will be difficult to implement.

Example with PHP

According what we just see, we need:

  • a function to send a query to Delicious and get the result,
  • a tool to parse the result (XML file).

PHP provides some functions to parse XML files since the version 4. But in this version, functions aren’t very useful. Since PHP 5, we have a set of functions named SimpleXML, very simple and easy to use.

Two main approaches:

  • We separate the query and the parse part,
  • We put all operations together.

The second solution is very simple, because we have a function to do that:

1
2
3
$username= ... ;
$password= ... ;
$xml_list = simplexml_load_file('https://'.$username.':'.$password.'@api.delicious.com/v1/posts/all?');

The function simplexml_load_file sends the query, gets the results, and parses them. The $xml_list is a PHP object.

I prefer the first approach:

1
2
3
4
5
6
$cache_file = ... ; 
$username= ... ;
$password= ... ;
$xml_string = file_get_contents('https://'.$username.':'.$password.'@api.delicious.com/v1/posts/all?');	
file_put_contents($cache_file, $xml_string);
$xml_list = simplexml_load_string($xml_string);

In this solution, we separate the query and the analysis. Operations are not so much more complex, but they allow to store results of the query, in a cache system (line 5). The function simplexml_load_string works in the same manner than simplexml_load_file.

Once the result is parsed, we can analyze it or transform it:

1
2
3
4
5
6
foreach ($xml_list->post as $link) {
    $attrs     = $link->attributes();
    $href      = (string)$attrs->href;
    $link_name = (string)$attrs->link_name);
    echo '<a href="'.$href.'" Title="'.$link_name.'">'.$link_name.'</a>';
}

Conclusion

Delicious provides a set of interesting tools. For our purpose, the synchronization, we can keep:

  • The API HTTP allows full synchronization of links and tags,
  • Incremental synchronizations can be performed with both HTTP and RSS feeds.

These tools have some small defects: first, they don’t allow to detect deletion. Then, in the case of HTTP, the security system is very sensitive, and will require to limit the number of queries, and to use a cache system.

A good API in Delicious side is not enough to perform a synchronization with WordPress. In a next post, we will study the WordPress API.