The Downhill XML-RPC API

Downhill, the intrepid link diver, has an XML-RPC API which allows you to access its functionality through any interface you feel like writing. You can use the Downhill API to get the shortest path between two weblogs or to get weblogs that match a string prefix. You can also do lookups against the weblog ecosystem data on which Downhill is based, or pick random weblogs from the dataset.

You can access the API by appending xmlrpc/ to the regular downhill.cgi URL, making it downhill.cgi/xmlrpc/. Unless you've set up your own instance of Downhill or know someone who has, this probably means http://www.crummy.com/devel/downhill/downhill.cgi/xmlrpc/.

If you write an interesting application using the Downhill API, please drop me a line and let me know about it.

Enough with the jibba-jabba! Show me an example!

Here is a sample Python script which exercises all of the API's functionality.

Enough with the example! Show me the jibba-jabba!

Access to weblog ecosystem data

I couldn't find any existing XML-RPC API to the weblog ecosystem data, and it was easy to put it into the Downhill API, so I just put it in. It consists of the following methods:

• downhill.getCanonicalURL(string url): Returns a string containing the canonical URL of the weblog whose URL you specify. For example, you can pass in 'crummy.com', 'http://crummy.com', 'http://crummy.com/', etc. into here and it will return 'http://www.crummy.com/' for each of those.

  If you pass in the empty string, you'll get the URL of a random weblog. Otherwise, if there's no weblog in the dataset corresponding to the URL you specify, it will raise an exception.

• downhill.getName(string url): Returns a string containing the name of the weblog whose URL you specify. For example, if you pass in "crummy.com", it will return "News You Can Bruise", since that's the name of the weblog at http://www.crummy.com/.

  If you pass in the empty string, you'll get the name of a random weblog. Otherwise, if there's no weblog in the dataset corresponding to the URL you specify, it will raise an exception.

• downhill.getOutgoingLinks(string url): Returns a list of strings, each string being the URL of a weblog linked to by the weblog whose URL you specify. The list will be empty if the weblog has no outgoing links.

  If you pass in the empty string, you'll get the outgoing links of a random weblog. Otherwise, if there's no weblog in the dataset corresponding to the URL you specify, it will raise an exception.

• downhill.getIncomingLinks(string url): Returns a list of strings, each string being the URL of a weblog which links to the weblog whose URL you specify. The list will be empty if the weblog has no incoming links.

  If you pass in the empty string, you'll get the incoming links of a random weblog. Otherwise, if there's no weblog in the dataset corresponding to the URL you specify, it will raise an exception.

Downhill-specific functionality

This is the code which goes beyond simple access to the ecosystem functionality.

• downhill.getMatchingURLs(string prefix): Returns a list of strings, each string being the URL of a weblog whose URL begins with some portion of the URL prefix you specify. For instance, if you pass in "food" or "http://food", you could get URLs beginning with any of "food", "foo", "fo", or "f". It will return a maximum of 10 URLs. If you try to match the empty string, it will raise an exception.
• downhill.shortestPath(string url1, string url2, [array exclude]): Returns a list of strings, each string being the URL of a weblog. If the list is not empty, it represents the shortest path from url1 to url2 that doesn't go through any of the URLs mentioned in exclude. If you want it put more formally, the list has has the following properties:
  1. The first URL in the list is url1
  2. The last URL in the list is url2
  3. None of the URLs are found in exclude
  4. For all 0 <= i < len(list)-1, the weblog designated by list[i] links to the weblog designated by list[i+1].
  5. There is no shorter list of URLs in the dataset that satisfies properties 1-4.

  If there is no path from url1 to url2, the list will be empty. If url1 and url2 represent the same weblog, there will be only one URL in the list. If you pass in the empty string for url1 and/or url2, a random weblog will be used in its place. If you pass in a URL not in the dataset, it will throw an exception.