7 Tips to Write Great API Documentation

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:

1. Create a Consistent API That Follows Convention
2. Write API Documentation That Decision-Makers and Developers Can Understand
3. Great API Documentation Is Intelligently Organized
4. Minimize Tech Jargon When Possible
5. Detailed Request/Response Cycle Documentation
6. Additional Perks and Information
7. Automatically-Generated, Interactive Swagger Documentation

1. Create a Consistent API That Follows Convention

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.” 

2. Write API Documentation That Decision-Makers and Developers Can Understand

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:

• “After 12 years, I still struggle with new APIs. Sometimes the APIs are complex (PayPal and Stripe, for instance) have multiple integrations and multiple APIs, so it takes time to understand which calls should be used with which integration. Even when the documentation is clear, and example code is provided, it is sometimes written for a platform I am not using, a dependency that doesn’t exist or is not compatible with my build, or some other technical roadblock. At that point, there is no choice but to Google for code samples specific to your set-up. Of course, you will run across incorrect and outdated samples, but you will try them anyway just to get things to work (source).”
• “I’ve done my fair share of integrations with external systems. I’m not sure what is worse, a clear but undocumented API. Or one that’s documented so badly that nothing that actually makes any sense (source).”

To ensure that your API documentation “makes sense” to the developer audience, make sure your API documentation provides the following:

• A quick sense for what the API can do.
• Instructions, examples, and code samples for calling each service that the API makes available.
• Concise, clear, and easy to read language.
• Up-to-date information for the latest API version.

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.

3.   Great API Documentation Is Intelligently Organized

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:

• Authentication: This section tells API consumers how to use your API’s authentication schemes. Carefully walk developers through each step of the authentication process in a way that there’s no chance of confusion. Here’s an example authentication guide from Twilio. 
• Error messages: It’s important to clearly define all error messages and error codes. Describe the parameters that trigger each error notice, and suggest fixes to resolve errors when they occur.
• Resources: Resources are the services and components that your API offers to clients and users. This section should (1) serve as a catalog for all available resources; (2) clearly explain how clients/users integrate with each resource; and (3) provide information and examples about requests/responses related to the resources.
• Terms of use: This section defines the legal terms of use that your organization and API users have agreed to. It should provide usage guidelines, legal terms and conditions, and spell out API limits and constraints. Here are the API terms of use for LinkedIn.
• Changelog: The changelog lists each API version and any implemented updates. It tells developers if they need to adjust the way they make API calls in different versions. It also shows decision-makers how often your organization is updating the API. Here’s an API change log example from StackExchange.

4. Minimize Tech Jargon When Possible

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. 

5. Detailed Request/Response Cycle Documentation

(Image Source)

When it comes to request/response cycles, give detailed explanations by keeping these principals in mind:

• Document all of your calls and provide contextual information: Document each possible call and its available parameters. Give contextual information, example scenarios, and practical details that help the reader understand.
• Explain responses and error messages for all formats: Describe all responses and error messages and don’t leave out descriptions for any of the formats that your API is compatible with (JSON, XML, BSON, form-urlencoded, etc.). Also include the following: definitions for HTTP headers, messages, and error codes; examples in the objects that the API returns; and examples for the different parameters developers can implement in their calls.  

6. Additional Perks and Information

Adding additional resources to your API documentation is not required, but including any of the following will offer a world of difference to developers:

• Educational guides: API documentation that strives to educate users with informative resources helps new users understand how to work with your API. Twilio’s API documentation starts from the ground up with educational materials that teach users about APIs. 
• Quick-start tutorial: A quick start guide illustrates each step required to quickly integrate with your API. Here’s a quick start guide from Spotify as an example. 
• Code libraries: Whether you’re a new developer or not, there’s nothing like a code library to save time. Code libraries offer pluggable snippets of code for different actions in the widest variety of languages. Here’s a great library example from Stripe.
• Create a full SDK: Consider putting together a full SDK or devkit for your API. An SDK serves as a complete workshop for building apps/products that use your API. It includes documentation, libraries, tools, code samples, and guides. Swagger Codegen is an awesome resource to help you quickly create an SDK.
• Offer a free test environment: An API sandbox or testing environment lets developers try out your API before fully committing to the solution. For potential new customers, it’s a zero-risk opportunity to test drive your API.

7. Automatically-Generated, Interactive Swagger Documentation

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:

• It’s interactive: Swagger documentation is interactive. You can point-and-click through various fields to explore different types of requests and the parameters available for the requests. These features let you generate an API call and see the result directly from the Swagger UI. 
• Excellent user experience: Swagger’s interactive documentation is nice on the eyes and a joy to navigate.
• Open-source: Swagger is free for anyone to use. 
• Big tech loves it: As a machine-readable solution for documenting REST APIs, Swagger has become the darling of big technology firms like Microsoft, Google, and IBM. 
• Stellar reputation among developers: Developers frequently praise Swagger documentation, like this Reddit user: “Swagger documentation is fantastic. In-line “try it now” boxes, example input and output json/xml, full model specification… mmm, love me some swagger documentation.”

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:

• The Swagger part of your API documentation will always be up-to-date. As soon as you update the API, you’ll update the Swagger documentation too.
• Because DreamFactory offers role-based access control, you can control how deeply users can interact with the docs. This allows certain users to have a surface-level view while permitting others to make edits and changes. 
• DreamFactory lets you import OpenAPI specifications for remote and scripted APIs.

Final Thoughts on Great API Documentation

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!  

Jeremy H

Fascinated by emerging technologies, Jeremy Hillpot uses his backgrounds in legal writing and technology to provide a unique perspective on a vast array of topics including enterprise technology, SQL, data science, SaaS applications, investment fraud, and the law. Contact Jeremy at [email protected].