Designing Great API Docs

One of the most important and easy ways to avoid frustrating API docs is to check them periodically to make sure nothing is out of date.

Last year I started using Amazon's Flexible Payment Service (FPS) and their docs were so out of date that they linked me to a PHP library that was over three years old and already deprecated. I spent weeks getting my billing system working and then as soon as it went live I got an email from Amazon telling me that I was using a deprecated library that was being phased out in the next few months.

I also had the same experience with Twilio, although luckily with them the old library didn't work at all so I didn't waste time developing with it.

Updating basic things like links to helper libraries can save your customers countless hours of headaches and frustration.

Another great resource:

http://jacobian.org/writing/great-documentation/

Soundcloud's API docs are quite impressive esp. their use of apigee console to test things out in the browser: http://developers.soundcloud.com/docs/

There's also a startup dedicated to (startup) API docs :) http://turnapi.com/

This is just as crucial as building your API properly, IMHO. I should be able to piece together my API integration from a mixture of examples, good documentation of deep features and caveats, and intuiting API methods.

For example, this API method (comes from real docs) is far from RESTful and leaves me guessing; what's the path for POST-PUT-DELETE (note, when I looked in the docs, API paths for those methods were not named POST/PUT/DELETE like this one is named get...)?

    https://myapp.com/api/v2/USERNAME/KEY/xml/company/get

I won't rant about API design as some HN'ers have posted excellent articles on proper RESTful API design already.

Docs that are out of date (I loathe developers that don't keep API docs up-to-date), misspell in examples or have un-tested examples, or generally are confusing to navigate are ridiculously unfriendly.

In relationship to this post whats everyone thoughts on smart docs like Posterous has? aka Mashery I/O docs, Swagger?

It takes the API explorer model to the next level....and integrates with documentation.

You get up to date docs + API explorer + code stubs. Is this the future?

What tools are out there to generate an HTML doc of your api? I don't necessarily need it to parse my code, but I want to take the busy-work out of coding HTML.

I so wholeheartedly agree. I was just thinking about writing about the decline and fall of documentation.

It seems to me that as open source software has risen, good documentation has declined. That is probably inevitable, but it doesn't make it good.

If you can wrap your mind around making your documentation every bit as elegant as your code, you'll win friends and score career points.

this is a good description of the individual concerns, but it's missing a really important consideration that most API designers seem to ignore: what's the ideal way (or ways) for someone to use your API? once you have some answers to that, you can start designing an onramp to your API that subtly guides developers towards the kinds of idioms that you want them to learn. it's not just a matter of following the right form in the right example, but overall organization--what concepts are introduced as being related, the kinds of examples you have at all, etc.

Are there any decent open source applications that I can launch to create pretty API docs?

I see that GitHub says their API is Open Source, but is that the actually contributing to the API examples, or the actual code?

I wanted to invest in Twilio after I saw the documentation.

And don't forget to include a reference to day9.