The number of web APIs is increasing fast, particularly with the recognition of SaaS. As web APIs are still quite new, the excellence and layout of their documentation differ a great amount.
Good documentation is significant in supporting and keeping developers involved in your platform in addition to decreasing support prices. Preferably, documentation should include four areas like an overview, getting initiated, sample code, and suggestions. Additionally, this post explains best tips specifically for web API documentation.
In order to reduce the amount of work in creating API documentation, it is helpful to find out how much of the documentation you can make involuntarily. Under the condition of SOAP-based APIs, you can take the detail in the WSDL and employ it to produce documentation pages. By employing the best web API documentation tool, one can involuntarily produce help pages for its REST services.
Bear in mind that auto-created documentation is just an initiation point. You will still require descriptions of all of the attributes, as well as summary stuff.
Add Sample Code
More than something, developers love to include sample code that they can study with and initiate a support for their individual work. One of Web APIs potencies is that they are autonomous platform and programming lingo. Unluckily, this comes out in additional work when developing documentation. You should be capable of making API calls in Ruby, Python, Java, C#, PHP, and almost immediately. Do you require creating sample code for all of these languages? That might not be sensible. In its place, know which kind of languages is most employed by your clients and concentrate on those.
Illustrate example requests and replies
Additionally to the sample code, including HTTP, XML, and JSON samples of your application and reply is significant. Though, samples only are not enough. On top of that, you require a description that clarifies the aim of the call and you require a table that elucidates every element. We suggest a table with columns for Name, Description, Type, and Remarks.
Elucidate authentication and error management
Authentication is generally needed for Web APIs, so you will be required to document how to get documentation and how those documentations are submitted to the Web server. You may require step-by-step lessons on how to get API keys. Sample code is generally helpful representing developers how the keys function.
You will be required to clarify how errors or mistakes are dealt as well. For instance, an HTTP call may ask for data employing unapproved documentations, or it may ask for an action employing data that does not subsist. At the moment there is no customary method to pass error or mistaken detail back, so developers are required understanding how you are passing again error detail, why an error takes place, and how to fix the issue.
In conclusion, remember that web APIs are developed on top of HTTP, which includes its own data. So, you may get HTTP-linked data that needs documentation too.