Good API Documentation

So you're a developer (you're not a developer? then maybe this post isn't for you, but feel free to read on), and as with most developers you spend a lot of your time looking up things on Google, Stack Overflow or various API documentation (API docs).

The quicker we can find the information we need in these API docs, the quicker we can build the next game-changing web app. So what makes good API docs? Read on and I'll tell you.

We've all been there; you're "in the zone", just written loads of totally awesome code but can't remember the parameters for a function you need to use. No problem, you bring up Google, enter the name of the function (and maybe the language you're using or something else to get a better result, you know the drill) and BAM the top result sounds perfect. However it's not, the information is out of date and of course you don't find this out until you actual test your code some time later and it takes you hours to track it down to this one bad source of information.

So let's start at the beginning.

Accurate & Up to date

This is the most important aspect of any API docs and thankfully most producers also realise this and do their best to ensure theirs stay up to date. The best of these are any that are built automatically from the API source; javadoc and rdoc, for Java and Ruby respectively, are great examples.

What about maintaining API docs for multiple versions? Well, either have the complete set of docs for each version available separately like the Java API docs (1.4.2 / 1.5.0 ) or show clearly which version(s) a particular page/function/method applies to, check out the documentation for the jQuery .live() function.

Clear, concise and well structured

Having accurate and up to date documentation is next to useless if developers can't find anything. Unless the entire API docs take up barely more than one screen (exactly what 'one screen' or 'the fold' is can be saved for another time) there has to be a good excuse to not have a search function. Search has its place but some people prefer to navigate to what they're looking for so the API docs need to be very well organised, with a clear hierarchical system if necessary. Both of these need to be consistent, if something can be found via the search system it really should be able to be navigated to also, and vice versa.

There are some great examples of this all around the web; the latest jQuery API site is excellent, as is APIdock (which gets bonus points for also having archives of every past version) and the vzaar API docs.

Examples

Being well structured is all well and good if you know what you're looking for but for first time use the best place to start is with a tutorial or examples. Many times I have found that just looking over an example can be far more useful than pouring over pages and pages of documentation. It's also good to see a mixture of examples, ideally at least one simple example and a more complicated one.

Open source projects are often full of good examples in the documentation. There's no better way to encourage developers to use (and potentially help develop in future) your latest open source project than to provide them with a plethora of examples. Here are a few I used recently: Authlogic, Whenever and Cache Money

Discussion

Examples are great, but it's not feasible to come up with every possible use for the API. Why not let the developers do this, provide them with a great discussion environment; forums, mailing lists, IRC etc. This will also reflect well for prospective developers who will see an active community as a positive thing.

The PHP API docs are a great example of this, see the page for the strpos() function for example. Facebook has been making great progress on its API docs lately, but before that the best place to get information was in their developer forums.

Sandbox & Playground

For very large APIs its helpful to have a developer area where you can try out API calls with different inputs and see their outputs. Flickr have really nailed this with their API Explorer where you can try out any of their API with full debug output.

Going one step further, it would be really helpful to have access to a sandboxed version of the API. This allows creation of data that is completely separate and isolated from the live data but still operates in the same manner. For some application this is essential, particularly when developing with financial transactions. Luckily PayPal have a full sandbox environment where you can create accounts, balances, card and bank account all that respond to the public API.

Anything else?

I'd love to hear what else you think good API documentation needs and your opinions on any great or terrible API docs out there, drop me a comment below or contact me on twitter.