Re:Designing Great API Docs
by the_bear on Wednesday January 11, 2012 @08:53PM
(#3454717)
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.
Re:Designing Great API Docs
by jsankey on Wednesday January 11, 2012 @11:57PM
(#3455107)
For this reason I would say you need to automate as much as possible. Maintaining quality documentation is expensive, and although much of it requires a human eye there should be plenty of opportunity for machie verification too.
For instance, code examples (snippets or sample projects) should be actually compiled and tested, automatically, every time the docs or the API itself changes. Think of it as CI for your documentation.
Re:Designing Great API Docs
by johns on Thursday January 12, 2012 @02:53AM
(#3455452)
I'm sorry you ran into the issue with Twilio. I'm in the position now where I can find and fix all of these issues so hopefully you won't see that happen again. If you email me your shirt size and address, I'll try to make it up to you. [email protected]
Re:Designing Great API Docs
by Ixiaus on Wednesday January 11, 2012 @03:56PM
(#3453643)
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...)?
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.
Re:Designing Great API Docs
by typicalrunt on Wednesday January 11, 2012 @06:12PM
(#3454158)
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.
Re:Designing Great API Docs
by sabman on Wednesday January 11, 2012 @06:27PM
(#3454216)
A bit out of date but I have used rapi-doc in the past: https://github.com/sabman/rapi_doc for some of our internal API reference docs, for quickly reminding ourselves of the current state of our API's. It's for Ruby on Rails though, so if you are familiar with RoR, it will parse your controllers looking for API related comments for each controller action. Here's an example https://beta.spacialdb.com/apidoc/layers.html But I am sure there are better tools out there, I'd be keen to learn about them.
Re:Designing Great API Docs
by twakefield on Wednesday January 11, 2012 @06:35PM
(#3454235)
We used sphinx (http://sphinx.pocoo.org/). Uses reStructedText and you can pull in comments/samples directly from your code to help make sure everything's up to date.
Re:Designing Great API Docs
by samg_ on Wednesday January 11, 2012 @06:48PM
(#3454288)
It's in a very early stage (not production ready), but some colleagues and I have been working on a automated testing DSL built on top of RSpec that lets you generate API documentation from tests which validate the documentation is correct. It requires RSpec and a Rack-compatible service (incl. Rails). I think the idea has legs.
Re:Designing Great API Docs
by wazoox on Thursday January 12, 2012 @03:09AM
(#3455500)
I like ROBOdoc [1]. It's not well known enough IMO, but it has the huge advantage to work with about any language you can think of, which is a real boon for mixed codebases (for instance C + Python + HTML + Javascript or any other combination you can think of). Of course it can be used to generate HTML, PDF, man pages, POD or about anything else.
Re:Designing Great API Docs
by tmurray on Wednesday January 11, 2012 @04:16PM
(#3453718)
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.
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.
For instance, code examples (snippets or sample projects) should be actually compiled and tested, automatically, every time the docs or the API itself changes. Think of it as CI for your documentation.
http://jacobian.org/writing/great-documentation/
There's also a startup dedicated to (startup) API docs :) http://turnapi.com/
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...)?
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.
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?
https://github.com/zipmark/rspec_api_documentation
[1] http://www.xs4all.nl/~rfsber/Robo/
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.
I see that GitHub says their API is Open Source, but is that the actually contributing to the API examples, or the actual code?