Best Practices and Tools for Documenting APIs

Our series on getting the most ROI out of your API walks you through all of the key aspects of building an effective API strategy and discusses the various options you can make at each stage of your journey. So far we have looked at business decisions and aligning with overall business goals, including building a team, treating an API as a product, choosing an architecture type and specification format, selecting an API tech stack, and securing your API.

Now your API is production ready, and you will need to provide documentation to consumers so they can integrate the data and services you have exposed via API quickly.

When to start thinking about documentation is a difficult decision. We could easily have placed this chapter as the third or fourth in the series. Definitely, when you are documenting the business case for your API and mapping the developer customer segments and customer journeys that will reflect their usage, make sure to share this work with your team. Also, be sure to reference it regularly when making API requirements and when mock testing the responses to your API.

As Jarred Keneally discussed in the Product Management chapter and Abhinav Asthana shared in the API Tech Stack chapter, tools like Postman can help internal teams document their API as they are building it, helping them ensure that their collaboration consistently speaks to a single source of truth concerning how they are designing the API.

"I would differentiate the early modeling and design type of documentation from the later documentation, which you don't really need until you have third parties," says Marc MacLeod, founder and CEO at the API lifecycle tool Stoplight.io. Once documentation is aimed at third parties, it still needs to reference the use case and requirements modeling, especially regarding how the authentication and rate limiting work. While Stoplight offers a documentation tool, they are also working on Scenarios, a beta product that MacLeod believes will create a new type of documentation based on user stories.
 

Jennifer Riggins

"We are layering in scenarios in our documentation. This shows you how to do discrete things like import or export a specification and how to publish a spec. We include these as scenarios in our documentation," he says.

ProgrammableWeb writer Jennifer Riggins recently completed a research project assessing the state of the API documentation market for the APIdays event series and its partners. She found that too often "API documentation is a beloved but neglected friend." Her comprehensive study found that one of the key measures of whether documentation is doing its job is if it helps developers speed up "time to hello world" (when they can make their first successful API call). She believes the biggest mistake with documentation is a set-and-forget mindset, where documentation is created once and then left alone rather than having continual investment in keeping it updated.

Régis Martin, co-founder of Wildnode, an API consultancy, says when working with new clients, "we insist on the importance of a well-documented API." He says his team usually points to the Spotify API developer portal as a good example of documentation designed to be useful to developer customers. Companies often feel documentation development is an investment, says Martin. "We struggle a little to encourage them to put that investment in the documentation; it requires some push on our part," he says.

Kristen Womack

"Your documentation is basically a map showing people how to access and use your API," writes Kristen Womack, co-founder of Night Sky Web Co. She says that documentation should identify key user segments and should be organized in a way that walks each segment through the corresponding use case. Language should be clear and plain throughout. Documentation should be well designed and focus on usability. It needs to have some form of changelog or automation with the core API design, so that it is always in sync. Finally, Womack says your documentation should be functional. You should create examples that users can work with, embed, and even test within sandbox environments, so they have the capacity to see in real time what a response would look like.

Marc Cuva, a engineer at documentation tool startup Readme.io, told the 2016 API Strategy and Practice audience in Boston that, "Documentation is the UX for your API." He recommends several strategies to go beyond the usual best practice in documentation.

Marc Cuva

One suggestion he made is to leverage personalization to make documentation pages more user friendly. "Documentation should be more than a static page. Treat it like a web app where documentation can adapt to the user," Cuva says. You can use a range of programming techniques that can recognize when a particular developer returns, with the simplest being to have developers log in when they visit the portal or to use cookies. Tools like the Clearbit Reveal API also enable web pages to understand who is visiting for the first time and where they're from. You can also adapt documentation pages so they surface particular information based on what's known about the developer visiting the page. If a developer is logged in and your API management analytics identify that s/he has just received an error page, when s/he goes to your documentation site, s/he should be directed immediately to pages that explain that error.

Akin to the transparency efforts that API providers like Salesforce.com take (i.e., Trust.salesforce.com), other documentation best practices argued by Cuva include having a status page that lets people check if your API has any other widespread problems or if it is just how they are using it.

Cuva recommends that examples of how to make calls should be complete within a documentation page, offering some sort of mock testing capability (i.e., a sandbox where the API actually responds with non-production or "mock" data) as well as a temporary API key from within the documentation that allows developers to sample the API without having to obtain his or her own key (we will discuss this more when we look at building a developer community).

The Role of API Specifications in Documentation and Testing

Choosing an API specification format (see Part Six: How to Choose Architectural Styles and Specification Formats For Your APIs) provides a great advantage for developing documentation. Having an API specification format describe your API allows documentation to be tested against the specification to make sure that all endpoints are described, sample code functions properly, and documentation overall matches the API's use case goals.

Many API providers also use API specification files to generate documentation automatically in chosen programming languages. The API specification format — which is in a machine-readable format — is scanned by the tool and documentation, often along with SDKs, are auto-created. For newer API providers who want to generate code quickly in a variety of programming languages, this is one technique they can use. However, several API providers report that the code generated by automatic tools can be patchy and cumbersome at times, often not reflecting best practices for generating code, as automatic generators tend to generate inelegant code that can suffer from bloat. Where SDKs are automatically generated, these still need to be tested in a mock server environment to ensure they function correctly, which in-turn will depend on developer time and resources.

An important and often overlooked aspect of documentation from a writer's point of view is to test the documentation once it has been created. That means creating a test environment and, after documentation has been written or auto-generated, using the test environment to to walk back through each code example in the documentation to see if it functions as intended. In teams, this can even be done by a technical writer colleague who was not primarily involved in writing or editing the documentation. When using API specification formats, it is also possible to auto-test elements of documentation within some API lifecycle tools to ensure that the documentation matches the specification.

Automatic documentation generators may be included as a feature in an API management platform or may be provided by an API lifecycle tool. There are also open source and independent automatic tools available (see our list below).

It may be preferable to use automatic generator tools to create code snippets in specific languages that can be shared in hand-written documentation rather than rely on an API spec and automatic generator to create the entire documentation. It is a potentially clumsy process, as software development expert Kevlin Henney says, "Code generation. So that you can do the wrong thing faster."

Some API lifecycle tools — like Postman and Stoplight — also provide automatic documentation generators direct from their platform, without having to use one of the more common specifications format like the Open API Specification or RESTful API Modeling Language (RAML). But, under their hoods, both tools are also relying on their own proprietary specification formats.  

A to Z of Documentation Tools

As noted above, API providers should begin creating documentation for internal developers when they are first designing the API. The majority of this part of our Decision Series has looked at the stage when documentation needs to be developed for external users — whether that be internal developers in other business units who are not part of your team, developers at partner agencies, or third-party developers who will enter via a self-serve portal to access your documentation.

There is quite often an evolution for API providers when first creating documentation. There may be some simple documentation created and used in conjunction with an automatic generator tool and an API specification. This allows an API provider to write some individual documentation pages, and then use the API specification file to auto-generate reference documentation which may explain each individual API endpoint and include a sandbox testing input environment so that documentation users can immediately make a sample API call and see what response they get. This may be enough to help some developers get started.

But to then really build a developer community around your API requires more detailed documentation and a range of other resources. Without a doubt, documentation is at the center of developer engagement. Good documentation can help developers:

• Get started using your API
• Understand authentication processes (and speed up their first successful API call)
• Make effective API calls that do not unsustainably call your backend too frequently or with bloated queries
• Inspire innovation off your identified use cases

Documentation may include getting started guides, API endpoint reference materials, and sandboxes.

But in addition to documentation there are a range of other resources that can be created and provided to developers including use case landing pages, design pattern maps, sample application code, community forums, SDKs, marketplaces to showcase successful apps and integrations, and blog posts. These latter elements make up part of a developer portal (covered in Part Eleven: The ABCs of Building API Developer Portals).

Next you need to decide which of the many noteworthy aspects of great developer documentation you should include in your developer portal. For example, you might just decide on the basics, such as great descriptions of all of your API's resources and how and when to work with them. Perhaps you want to layer on some sort of "playground"-like capabilities, such as a console of some sort that enables point-and-click interactivity to sample the API's responses (either with production data or with "mock" data) or an interpretive environment that can host sample or custom code for API experimentation in the developer's real-world context.

The more developer engagement items that you check off as must-haves, the more you will begin to appreciate the many tools that can assist, if not automate altogether, the provisioning of your API documentation and other developer artifacts (i.e., SDKs and sample code) that go with it.

You have a number of options when choosing which API documentation tool to use. Most API management platforms come with a documentation editor. Some of these are available as standalone services. For example, API management provider MuleSoft (and ProgrammableWeb's parent company) offers a documentation tool within its Anypoint API platform, but also available are standalone open source tools like API Console and API Notebook, which allow users to create API documentation directly (API Notebook) or from a RAML specification format (API Console).

Apart from tools that come with API management platforms and API lifecycle tools, you can turn to a number of independent services that can automatically generate documentation from APIs. You can also use some standard templates and documentation tools designed to help technical writers create engaging, formatted content quickly.

In addition, be sure to review the number of open source projects that help generate documentation either by hand or from an API specification format.

Using a suite of tools for documentation does introduce its own complexity. For example, some API management platforms include their own developer portal templates and documentation tools, such as sandbox testing. When using independent third-party documentation generation and support tools, you may have to test that the API management platform and the third-party tools read the API specification format in the same way. How the API management platform understands the API specification and how to process call responses could differ from sandbox examples and code snippets generated in documentation tools.

Below is a selection of the industry's more widely used documentation tools.

Agency OpenTech

Created by the U.S. General Services Administration's 18F team, this open source template is designed to help government agencies create API documentation for their government APIs. It is used like a CMS template with instructions on how to upload to GitHub Pages. Documentation must be handcrafted and must be edited and added as needed, rather than using a specification file to automate reference documentation or to provide a sandbox feature. The main benefit of this template is to provide the structure for a fairly standard looking set of documentation pages for use by a business or government agency, where developers can intuitively look around. It may be best suited to a small API with only a few endpoints where only a small number of capabilities are being exposed.

API Console

API Console is an open source tool that works with APIs that have been designed or modeled using the RESTful API Modeling Language (RAML). The RAML Console allows the browsing of API documentation and in-browser testing of API methods. The open source version of API console can be hosted on GitHub Pages or other cloud servers, or used as an HTML embed into an existing web page. It uses a RAML specification file to create automatically some overview documentation and detailed endpoint references. Build tools are provided to help developers create an API console instance in their preferred programming language.

API Notebook

API Notebook is another open source tool from MuleSoft that allows for the automatic generation of code snippets in JavaScript. As with the full documentation creation tool API Console, API Notebook imports a RAML specification file. The focus for API Notebook is to create individual pages that help run through code snippets and demonstrate how a particular resource of an API can be used. Where API Console auto-generates reference documentation for a complete API, API Notebook helps speed up the creation of handcrafted tutorials and API documentation pages by allowing writers to explain how to make calls for a particular API resource with runnable JavaScript code examples embedded in the page. Outside of using in MuleSoft's AnyPoint platform, API Notebook can be forked in GitHub and used on any website.

Apiary

While Apiary is a more rounded API lifecycle tool, it is often used as a documentation tool. Because the lifecycle tool also assists in designing the API, one benefit is its ability to generate automatically an API's documentation from the resulting design and to align the documentation closely with testing. Apiary can use a range of API specification formats but was originally built using the API Blueprint format. When creating documentation in the tool, you can import a specification file or use API Blueprint because the source and documentation can be auto-generated. Apiary also allows for mock servers and testing environments, so you can test the documentation against the original API specification. The Apiary community also provides a number of open source tools that can be used independently of the Apiary tool in combination with API blueprint to manage documentation. These tools include:

• Dredd: Reads an API blueprint or Open API Specification format file and checks it step by step against documentation to ensure that it is in harmony, and if so, allows any changes to be made in a continuous integration/continuous delivery workflow.
• Snowboard: Can generate API documentation (such as the Real World API) using an API Blueprint specification file.

DocBox

Docbox is an open source version of Mapbox's REST API documentation system. It takes structured Markdown files and generates a friendly two-column layout with navigation, permalinks, and examples. Docbox looks a little like a supercharged version of the Agency OpenTech tool. It does not seem to allow for the automatic insertion of an API specification file, so all documentation must be handcrafted, but it does go further than the OpenTech tool by including a test environment that checks that all sample code snippets included in the text function as intended, and the template includes embedded sandboxes that show sample responses to API calls.

DocSearch

Created as an open source community project by Algolia, DocSearch is not a documentation generator, but a search tool that helps API developer consumers more easily find the relevant documentation pages they need in order to use your API effectively. The Algolia team says they spend a lot of time reading documentation and are often frustrated by what they can find. Technical writer expert Heidi Waterhouse has commented that "by the time anyone is reading any documentation, they're already angry," and having difficulties locating the documentation resource to help them solve their problem can increase that anger. So having a thoroughly indexed, autocomplete-capable search tool for documentation pages can be a great help for developers using your API.

For example, Stripe has embedded this tool as its search functionality at the top of its documentation pages. Any API provider can provide its documentation URL for free to Algolia. They will index the documentation pages and provide a short code snippet for use on any documentation site that enables Algolia's functionality to drive the search tool.

Hitch

Hitch is a community development tool aimed at helping API consumers source APIs and manage their own internal APIs more effectively. Where an API specification format file has been provided, Hitch automatically generates endpoint reference guides, as developers have done with music notation software API, Flat. Additional guides are also provided for some APIs, written by key industry experts like regular ProgrammableWeb contributor Chris Wood, who wrote the getting started guide for the Instagram API on Hitch. In its changelog feature, Hitch also documents any changes to API documentation so that API consumers are aware of any breaking changes that may impact on their applications.

LucyBot

LucyBot offers automatic API documentation generation from an API specification file in OpenAPI, RAML, API Blueprint, and WADL formats. It includes a console for sandbox testing, encourages customer journey mapping, and includes sample code generators. A non-commercial licence is available free of charge as an open source project while business use and additional features such as event and engagement tracking, multiple API doc version management, support desk, and capability to add additional HTML pages to the docs are offered as paid services in a per-API cost structure. (This could be a prohibitive costing structure for providers who have organized their APIs into discrete functionalities rather than as a single API with multiple capabilities and/or data assets.) LucyBot includes an API console that allows for the inclusion of a sandbox-like feature within documentation so developers can test API call responses within documentation. It also has an interesting workflow tool that helps API providers describe how to consume their API for particular use case scenarios. This concept of sharing design patterns for common use cases is a growing approach to API documentation.

ReadMe

ReadMe provides four key documentation assets: a documentation landing page, auto-generated reference pages created from an Open Archives Initiative (OAI) specification file, a sandbox-like interactive "API explorer," and the option to add handcrafted documentation pages alongside the autogenerated reference guide. This is a paid service with a minimum set of documentation tools that API provider hosts on its custom domain. ReadMe also offers higher-cost plans with additional features such as the ability to include custom JavaScript on pages, user authentication management, and custom terms of service documents.

Read The Docs

For API providers with an open source project, Read The Docs may be a suitable choice for auto-generating and hosting API documentation. With Read The Docs, users can identify how they want their documentation to be created in either a Python documentation generator Sphinx file or a MkDocs Markdown file format. Users enter the GitHub repo name where their project is stored (for example, their open source API project), and Read The Docs will automatically generate and host the documentation at the main Read the Docs site. Having an open source project's documentation shared in the Read The Docs library may also be a way to aid discoverability of the API documentation among the open source community. Additional features are available, including the ability to link Google Analytics to the documentation so that API providers can track engagement, as well as the ability to host the documentation generated a provider's own domain.

One of the main benefits of using Read The Docs is its leverage of a "continuous documentation" mindset. When changes are made to the GitHub repo for the API source code, the documentation is automatically updated to reflect those changes.

Rigetti Computing, which recently released open source quantum computing APIs Forest and PyQuil, hosts its documentation on Read the Docs.

Slate

Slate is an open source, responsive API documentation generator that was originally built by TripIt and later adopted by many leading API providers. Over 9,700 GitHub users have forked the Slate repository, indicating many API providers are reusing this template (not all of them are production use cases, but it is used by notable providers for their APIs such as Travis-CI, Best Buy, and Clearbit). Content for Slate is written in Markdown and documentation is delivered in the industry-standard format where the menu is on the left pane, documentation in the middle pane, and an interactive sandbox in the right pane. While API providers must handcraft the documentation, they can link the sandbox to multiple bindings in an API so that tabbed windows are provided to interact with the API in over 100 programming languages, with programming syntax throughout the documentation automatically highlighted, just like in code editors. Slate automatically creates a GitHub repo with the documentation, which can then be published as GitHub pages, or downloaded as HTML, CSS, and JavaScript and hosted on any server.

SpringFox

Spring is a popular application framework for building applications in Java, and as part of the ecosystem, Springfox has been created as an open source tool that automatically generates documentation for APIs built with Spring. When an API has been written using products in the Spring ecosystem, they come with specific configurations, class structures, and compile time Java annotations. These are taken into account by Springfox when generating the documentation. Springfox can read from an OAI or RAML specification file to generate the documentation.

Stoplight Hosted Docs

Internal teams who are getting started using the Stoplight API design tool can use Stoplight's Hosted Documentation product as a standalone product, but they must move to a paid plan to share documentation with external developers or when usage hits a high enough level. APIs designed within the Stoplight tool use Stoplight's specification format to automatically spin up documentation and interactive sandboxes for mock testing of the APIs. API providers can enhance or edit in Markdown the auto-generated documentation. Editing features include customizing the layout and design of the docs, integrating with Google Analytics and Segment.io, and adding user authentication to ensure particular documentation pages are visible only to specific user roles.

SwaggerUI

SmartBear's SwaggerUI is in version 2.2.5 and is an automatic documentation and endpoint generation tool that includes an interactive sandbox for testing an API directly from an OAI specification format. After inputting the OAI file, each endpoint is generated automatically as a dropdown list that allows interactive mock testing of API calls within the documentation. Once generated, the API provider can host the documentation on its own site. SwaggerUI is often used by API providers who are just starting to expose an API to third-party developers. It is chosen frequently because it is a quick way to provide API reference documentation until more users begin consuming the API and the API provider has the resources to create a more complete documentation offering (including Getting Started guides and other in-depth documentation assets).

Documentation is a key enabler for external developers to make use of your API. And while key, it represents just one part of your developer engagement strategy. In our next chapter, we look at how to build a developer community.