I’ve integrated with, and also built, not a small number of APIs in my years, working on different web services, defining restful API's and more...

Over the course of integrating with and researching a bunch of APIs, I’ve looked at the documentation of the APIs I have worked with. The sad fact is, most of it is terrible. From poorly documented endpoints to a lack of code samples, I’ve spent hours pinging endpoints trying to get a request right because the documentation was so bad.

I’ve been working on a project where I’ve had to design - and document - a brand new API. The API is RESTful, and exposes services out to a number of clients. Pretty standard stuff.

As part of this project, I needed a way to document how we were designing the API architecture - all the endpoints, data models, all that. In our case, the API hasn’t even been built yet - we’re designing it completely, then going to build it.

“Great API documentation is essential” many people exclaim. So, you fire up your favorite API definition editor and start writing docs. You learn what RAML is and how to format it properly. You agonize over the URL paths, verbs, response codes, and payload definitions. Finally, you reach that glorious moment: “Documentation is done! Whew!” Not quite.

While it is an important step to create API reference documentation, focusing only on these docs can cause you to miss the hidden value that API documentation can bring to your customers and your team.

The Hidden Value of API Documentation

API documentation tells the story of your API. From the getting started guide, to core concepts and examples, your API documentation informs the audience about how you see their problem. As we know, we can solve problems using a variety of approaches and points of view.

Your documentation tells me your story: how you see the world, my problems, and your solution to those problems.

API documentation is the primary communication medium between API provider and consumer. Unless the API is open source, you will likely never see the source code behind it. Therefore, the only thing that developers consuming your API have is your documentation. Without clear and complete documentation, developers will struggle to use your API.

API documentation validates API design prior to implementation. By including documentation as part of the process and including technical writers during the design and development process, API design flaws can be spotted before coding has been completed – when changes can still be made easily and with minimal impact.

Beyond API Reference Documentation

We use the term “API documentation” as if there is only one kind of documentation. Yes, you need to deliver a great API reference for developers. Tools such as Swagger, RAML, and Blueprint are just a few of the formats available to help build them. However, complete API documentation requires more than just your API reference in HTML or PDF form. It requires looking at the marketing, development, and customer support aspects of documentation as well.

API Documentation Categories

As you see, it takes more than just generating an API reference to fully document your API. Let’s examine each of the options available to help compose your complete set of API documentation:

Marketing-Focused API Documentation

Features and Discovery – Provides an overview of the API, addressing concerns such as benefits, capabilities, and pricing of your API to qualify prospects. This may include marketing content for developers and key decision makers, as well as automated discovery through formats such as APIs.json.

Case Studies and Examples – Case studies highlight applications that have been built using your API. It is also useful for sharing usage of your API by applications that have been internally deployed and therefore not generally not accessible. You may wish to consider providing examples and reference applications to demonstrate some of your API’s capabilities prior to developer sign-up.

Development-Focused API Documentation

Reference Docs – Provides a reference for each API endpoint to developers, including details on the URL, HTTP verb(s) supported, response codes, and data formats. Developers use this documentation when starting to consume API endpoints, whether for the first or the tenth time. While some developers may use reference documentation to become acquainted with the API product, it is most often used for exploration, development, and troubleshooting. This is where Swagger, RAML, and Blueprint formats are used to generate documentation from an API definition.

Guides and Concepts – As an API consumer, the most difficult part of using an API is the initial learning curve. Guides offer help with learning an API’s concepts and vocabulary during this critical stage. They also provide step-by-step guides for implementing common use cases. Combined with links to reference docs sprinkled throughout, developers are able to get started quickly and with confidence.

Support-Focused API Documentation

Problem/Resolution – Sometimes developers need a little help when consuming your API. Documentation that helps developers troubleshoot error response codes can ease the burden on your developers and support staff. In addition, help pages and FAQs can guide new and experienced developers toward a better understanding of your API and proper usage patterns.

Internal Docs – For those instances when developers need more assistance with your API, it is important to have internal assets to help your support team. Don’t forget to create and maintain internal design documentation, including diagrams and code comments, which go a long way to debug difficult issues.

Putting it all together

There are a variety of online restful API documentation types beyond the typical reference documentation style we see today. Each one serves a different purpose to support the API both internally and externally. You will need to mix-and-match them depending on the purpose of your API to create a complete set of documentation. Be sure to select the ones that support your developers, your team, and the story your API tells.