Alex Bosworth’s How To Provide A Web API is a pretty solid primer for what we should be doing in our mash-up world. Web 2.0 is not only a revolution in user-centered design, it’s a revolution in user-centered data.

People want to be able to get at their data in any format they choose. They don’t want to have to visit your site, log in, and browse around before finding what they need: they want to be able to see it next to new blog posts in their RSS reader; they want to be able to jack it into an AJAX app they write for their blog.

So, how do you create a usable API? (And, believe me, as someone that’s used a lot of APIs from a lot of different applications, this is a question that needs to be asked a lot more). First, document the hell out of it. For every function you write, write a concrete *-doc version that explains it, then go a step farther: show the code in actual use (Ruby on Rails does a good job of this); without examples, you have almost no idea what the API is expecting, or how it should be used. (Call me crazy, but I like to see how functions are called, and what they return in actual code rather than having to infer it from a method signature). How else can we make these things better? Jared Spool wondered the same thing at UX Week 2006.

technorati tags:api, usability

Blogged with Flock

This entry was posted on Thursday, August 24th, 2006 at 2:57 pm and is filed under learn. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.