What I want from a good api

Christian Johansen tweeted

What's your favorite API documentation?

— Christian Johansen (@cjno) January 28, 2014

this morning to which I answered

@cjno The source

— Erik Assum (@slipset) January 28, 2014

He obviously was not impressed by that answer, so that got me thinking, what do I want out of a good api (documentation)

First and foremost, I want an api which lets me do what I need to do without learning everything about the api before getting my stuff done. So to start off, with one of the examples that Christian brought up in a later tweet, say I wanted to do something with Facebook.

First of all I’d like to have a client library in my favourite language so I could say something like:

var fb = Facebook.login('john@doe.com', password);

fb.friends().map(function (f) {console.log("this is my friend " + f )};
fb.news().map(function (n) {console.log("this is my wall " + n )};

var friend = fb.findFriend({firstName: 'Ola', lastName: 'Dunk'});
fb.post(f, {title: 'Hi Ola', text: 'Check out this cool api'});

fb.logout();

Having no idea what the Facebook api looks like, but some of the things I want: I want an api which speaks in the clients language and which is optimized for the clients tasks.

So I guess for an api like this I would like some tutorials which showed me how to achieve some common tasks, and then, yes, I’d love to be able to see the code behind it, so I could figure out how to do the stuff the api-designer didn’t know I wanted to do.

So to answer @cjno, the documentation I want for an api is a set of annotated, working, tutorials which show me how common tasks are achieved. If I then also could have access to the sources, I’d be as happy as could be. This is probably a good example.