As soon as APIs grew into a big business and an economy sprung up around them, documentation became a part of the game. Its importance cannot be understated, as the information it should provide may affect a vendor’s reputation greatly. Documentation can either win an API provider an army of happy API consumers or become a disaster scaring developers off and leaving providers to look disreputable.
To understand what features would be vital for their API documentation, providers should focus on their audience. All in all, the circle of potential visitors usually comprises the following important API users:
- developers looking to get started
- C-level execs evaluating competing APIs
- Product Managers puzzling out if the API can work for this or that
With the users mentioned above in mind, a pretty long list of features that API providers should consider including in their documentation can be made. Among them are those that can be regarded as basic ones and those that are rather optional, though desirable.
So, in this article, where are going to explore how to write API documentation and what it is essential to include in it.
Structure Points of API Documentation
While there is no standard of what an API documentation should look like, a few units, namely overview, getting started and description, can considerably ease users’ interaction with it.
The perfect API documentation is an extremely understandable one, which implies that a general overview is a must. Here API providers can explain why and how one would use their API and provide some use cases to emphasize its wide applicability.
Clearly not all the developers visiting the documentation page will be familiar with the API, so the getting started section should not be neglected. Programmers will indeed appreciate tutorials and any information on what is necessary to begin consuming the API.
The description part makes up the informational core that people will come to the page for. Thus, it is highly important to pay attention to, the more details, the better. The following tips will help you to write API Documentation and can be applied to ensure the information is presented in the most favorable way possible:
- document each API call separately, with parameters and their values explained
- provide examples of each call being made accompanied with details about the requests and responses ( GitHub )
- make it easy to find what is needed by adopting a menu of links ( Stripe )
- explain and exemplify request headers, API responses and error codes just as GitHub does. It is very helpful for newcomers trying to understand how an API call’s behavior can change based on certain HTTP request headers.
- provide developers with an ability to make live calls right from the documentation page ( 3scale and API2Cart )
- create clear tutorials for such complex issues as authentication. These will be much looked up by visitors having no previous experience with the resource you work with every day ( Facebook ).
- illustrate the best of your API by providing code samples in the most popular programming languages such as PHP, C#, Java, Go, Python, Ruby, Swift, etc. (see the top of Mailgun )
Other Points
Apart from the particulars mentioned above, there are at least 5 non-structural enhancements worth being considered if you want to write API Documentation. To make the docs as user-friendly as possible, API providers can take such suggestions into account:
- do not make descriptions too sophisticated because of not all the visitors are going to be developers, and even those who know how to code may turn out to be unfamiliar with the domain and jargon of the API. Documentation is intended to be clearly informative for anyone interested, so it is a good practice to add links to definitions and explanations
- let developers improve the content by making open-source contributions just as Parse does
- if possible, allow spreadsheet export in CSV, Excel or Google Spreadsheet format (some API consumers prefer working with CSV representations of APIs)
- provide instant help if needed
- make the text readable, copyable and embeddable (large and clear fonts such as Open Sans or Helvetica for non-code writing and Monaco or Consolas for programme instructions; and maybe a “copy” button)
Conclusion
The audience is the key to determining what an API documentation page should look like. It never hurts to ask for feedback and suggestions, for your users will often know best what would have made the experience even more informative and enjoyable. Meanwhile, the “dos” mentioned in the article make an excellent foundation for what API consumers visiting the documentation page will certainly like.
If you are responsible for developing a SaaS solution for retailers and need to connect your system with various shopping platforms, try API2Cart.
API2Cart provides a unified API for integration with 40+ eCommerce platforms like Magento, Shopify, OpenCart, and others. Usage of API2Cart allows you to manage the data easily from your clients' e-stores. It includes the info connected with orders, customers, prices, shipments, products, taxes, etc.
API2Cart has an excellent API Documentation, 100+ methods for working with data, 24/7 customer support.
If you want to know more about API2Cart and try it for 30-days for free, contact our manager right now!
