Dear API Developers, this is what I would like to have

Jonathan Boutelle of Slideshare reacted to my slideshare show widget and liked how I hacked around the API by re-using the RSS feed. He now asked in the comments what I’d like to see from an API. Well, here goes:

1. Allow for “hackable” URLs, with definition of the output. Flickr and Del.icio.us are good examples, especially the del.icio.us option of defining a callback for the JSON: http://del.icio.us/feeds/json/codepo8 gets me a JSON data wrapped in a Delicious object, http://del.icio.us/feeds/json/codepo8?raw gets me the raw JSON data and http://del.icio.us/feeds/json/codepo8?raw&callback=foo wraps it in a function call to foo(). This rocks! The same goes for defining the output as the last parameter. Flickr does that well – http://api.flickr.com/...format=json for JSON, http://api.flickr.com/...format=rss for RSS, http://api.flickr.com/...format=lol for LOLCAT
2. make sure that the JSON output is easy to use and does not have any annoying bits (encoded HTML or namespaced attributes – the description property in the flickr JSON to me is pointless weight for example)
3. make the URL as logical as possible, I don’t like to have to use the user ID in flickr for example when the readable user name would be easier to do.
4. it’d be great if you could send a unique ID as a parameter as that would allow you to match returned data to calls (as both dynamically created script nodes and Ajax calls may return in any order)

However, all of this does not replace the real API, which should

1. allow me to define only the data bits that I need (and cut down to the smallest possible feed – no twitter, 150kb JSON is not good!)
2. give me extras when I go through a developer ID. How about offering me free stats (even as an own API) when I build a widget that uses my ID - we do this now to throttle usage anyways. In a second phase this could also be used for a revenue sharing program.
3. offer things like enforced authentication (you know the photos you don’t want to show your mother)
4. allow for local caching methods (deliver the data gzipped for example)
5. allow me access to things that the open REST calls don’t (my sets, my favourites, my contacts, my profile settings)
6. be read and write – I want to build widgets that allow data entry from my blog to your systems, without leaving it.

Anything else?

Tags: api, JSON, REST, slideshare, wishlist