Ohloh.net (a pretty cool resource I use to look up Open Source projects’ stats) recently opened an API to their service. There’s a very nice touch there, the kind that seems obvious once you see it working but is actually pretty rarely used: XML URLs basically work exactly like the website’s “regular”, HTML URLs – you just add .xml to a URL and get an XML response (and also an api_key and version #, probably to make sure it’s not perfect. Why do so many APIs require a key? Most APIs are not exposed to any risk the normal, key-less HTML requests are.)
For example, say you’re looking at the Firefox project page, which is
http://www.ohloh.net/projects/9 – just append .xml and the version/api_key vars and you’ll get the same data in XML format: .xml and
GET http://www.ohloh.net/projects/9.xml?v=1&api_key=... (<-this link won’t work cause you need to get your own API key. Sorry ;))
The XML itself is easy to understand, especially since you can compare it to the HTML page, in case there’s a tag you’re not clear about. There’s some short docs on the response format in Ohloh’s API page, but I bet most developers wouldn’t need to read them.
This might seem obvious, but in fact it’s a very elegant, minimal solution that’s rarely used. Compare this approach to Amazon’s Web Services API docs to get an idea of how these things are usually done.