by Jeremy H
• August 11, 2020
Developers build REST APIs so people can use their applications, and they write great API documentation so people can use their APIs. But for some reason, writing API documentation that is both pleasurable to read and easy to work with is a skill that many developers lack, so let’s get this clear:
Your API is only as great as your API documentation.
Below, we explore seven tips for writing great API documentation. These tips will help you understand why it’s important to write great API documentation, the best strategies for going about it, and we’ll also show you how to dramatically speed up your API documentation process with DreamFactory – which can automatically generate fully-documented REST APIs in minutes!
Table of Contents:
Did you know you can generate a full-featured, documented, and secure REST API in minutes using DreamFactory? Sign up for our free 14 day hosted trial to learn how! Our guided tour will show you how to create an API using an example MySQL database provided to you as part of the trial!
Create a REST API Now
To write great documentation, you need to start with an API that’s consistent with naming conventions and follows common standards for behavior. Stick to what an experienced developer expects. For example, your API should use conventional HTTP status code definitions and verbs – i.e., 404 (not found), 400 (bad request), 500 (internal Server Error), DELETE (delete), POST (create), etc. An exception to this is PUT and PATCH, which may vary depending on the needs of your app.
Consider reviewing the REST Resource Naming Guide for more information about creating APIs that are intuitive and easy to use. According to thiguide:
“REST APIs use Uniform Resource Identifiers (URIs) to address resources. REST API designers should create URIs that convey a REST API’s resource model to its potential client developers. When resources are named well, an API is intuitive and easy to use. If done poorly, that same API can feel difficult to use and understand. The constraint of a uniform interface is partially addressed by the combination of URIs and HTTP verbs and using them in line with the standards and conventions.”
Before companies use your API, they’ll evaluate whether it solves their pain-points. This involves a close review of your app, API, and documentation by company decision-makers. These decision-makers won’t use your API directly, but they need to understand it. By keeping decisionmakers in mind while writing your docs – like CIOs, CTOs, and tech product managers – you’ll develop API documentation that “sells” your solution to the widest audience possible. An important way to do this is to avoid jargon, offer explanations for nuanced topics, and make the utility of the API clear.
The other important audience for your API documentation is the developers who will be calling and interacting with the API. Many of these developers struggle with bad API documentation on a daily basis. For example, these quotes from Reddit show you what they go through:
To ensure that your API documentation “makes sense” to the developer audience, make sure your API documentation provides the following:
When your documentation satisfies these requirements, developers are more likely to sing your praises – and that’s when your solutions become popular in the developer community.
The organization of API documentation depends a lot on the industry, but there are certain sections that developers have come to expect. Make sure to organize your API documentation into the following sections at a minimum:
Think back to the days when you were first learning about your industry. Your head was spinning with tech jargon that you didn’t understand. Some decision-makers and users could feel this way while exploring your API documentation, so do your best to support them by avoiding unnecessary tech jargon when possible.
When uncommon terms and industry-specific jargon are necessary, offer links and support material so readers can learn about these concepts. This will help everyone to understand the “why, what, and how” behind the API calls and resources associated with your product.
When it comes to request/response cycles, give detailed explanations by keeping these principals in mind:
Adding additional resources to your API documentation is not required, but including any of the following will offer a world of difference to developers:
This final tip will make your “great API documentation” journey faster and easier to complete. It involves DreamFactory, which can automatically generate Swagger documentation for your API projects. Swagger has become the gold standard format for API documentation for several reasons:
If you’re using the DreamFactory API gateway, there’s another reason you’ll like Swagger. DreamFactory includes automatic API generation tools that create REST API’s for any database in minutes. These APIs also come with full Swagger documentation. Here’s a screenshot of Swagger documentation that DreamFactory automatically generated for a SQL Server database. It’s an abbreviated list of REST API endpoints that you can explore by pointing and clicking:
When you click the second “GET” row labeled “Retrieve one or more records,” it displays a list of supported API parameters. Then, you can click on different parameters to identify the target table and the fields you want to retrieve. Finally, you can specify other functions like FILTER, LIMIT, JOIN, ORDER, etc.:
After choosing the parameters, you can see the actual results of the request:
Here are some of the benefits you’ll receive by incorporating DreamFactory and Swagger into your API and API documentation strategy:
By keeping the above tips in mind, you should be able to write the kind of API documentation that encourages decision-makers to adopt your technology, and helps developers quickly integrate your solutions after that decision has been made. Ultimately, when you write great API documentation, developers will love you for it – and that’s how your API becomes legendary!
If you want to speed up your API documentation process with automatically generated REST APIs that come with full Swagger documentation, contact the DreamFactory team for a free, hosted trial now!
Join the DreamFactory newsletter list.