What is best tool to document API

Comparison:
rackspace
netflix api
go-grid
aws api
https://www.twilio.com/docs/api/rest
https://developers.google.com/+/api/

Good:
https://developers.facebook.com/
https://www.twilio.com/docs
https://developers.facebook.com/docs/
http://developers.soundcloud.com/
https://www.layar.com/documentation/browser/
https://dev.twitter.com/docs/streaming-apis


Best Practice:
1.

Lesson Learnt:
1.  ProgrammableWeb is a catalog which has all the APIs.
2.  



Best Practices:
1. Good documentation is important in encouraging and keeping developers interested in your platform as well as reducing support costs. Ideally, documentation should cover four areas, as shown in the figure above: overview, getting started, sample code, and references. In addition, this article describes best practices specifically for Web API documentation.
2.

Auto-generate Documentation

In order to minimize the amount of work in writing API documentation, it's useful to see how much of the documentation you can create automatically


Include Sample Code

More than anything, developers like to have sample code that they can learn with and start as a base for their own work. One of Web APIs strengths is that they are independent of platform and programming language. Unfortunately, this results in extra work when creating documentation. You should be able to make API calls in Python, Ruby, Java, C#, PHP, and so on.

Show Example Requests and Responses

In addition to sample code, having HTTP, XML, and JSON samples of your request and response is important. However, samples only are not sufficient. In addition, you need a description that explains the purpose of the call and you need a table that explains each element. We recommend a table with columns for Name, Type, Description, and Remarks.

Explain Authentication and Error Handling

Authentication is often required for Web APIs, so you will need to document how to get credentials and how those credentials are passed to the Web server. You may need step-by-step instructions on how to obtain API keys. Sample code is often useful showing developers how the keys work.

You'll need to explain how errors are handled as well. For example, an HTTP call may request data using unauthorized credentials, or it may request an action using data that does not exist. Right now there is no standard way to pass error information back, so developers need to understand how you are passing back error information, why an error occurs, and how to fix the problem.
Finally, remember that Web APIs are built on top of HTTP, which contains its own data. So you may have HTTP-related information that requires documentation as well. This can include caching, content type, and status codes.

Examples to Look At

If you talk to people in the Web API industry, one example often comes up as documentation that's done well. That's Twilio, which delivers cloud-based telephony and has excellent documentation.

What have they done right? First, they've got all of the pieces that a developer could ask for: tutorials, sample code, overviews, references, and an error and warning dictionary. Their reference material is well-organized, breaking information down into the Base URI, a table of properties, and HTTP methods (GET, POST, PUT, and DELETE, each with XML examples and description). In addition, they've got nice formatting that matches the look and feel of their overall website, and they have a good navigation system.

References:
http://www.programmableweb.com/news/web-api-documentation-best-practices/2010/08/12
http://bocoup.com/weblog/documenting-your-api/
https://www.braintreepayments.com/blog/api-where-to-begin
http://www.jpsoftwaretech.com/documentation-best-practices-for-web-apis/
 [Very Good]
http://www.slideshare.net/NathalieSteinmetz/web-apis-best-practices
http://www.slideshare.net/ibmapimgmt/recommended-practices-for-designing-a-web-api

Taxonomy: - Walked through the API Catalog of following APIs
https://www.twilio.com/docs/api/rest
http://docs.rackspace.com/