API consumers succeed when there is robust documentation, as we’ll cover here. This article is the first of several that will tackle API design topics in depth. Expect to see forthcoming articles on practical ideas like design-first principle. Today, we will be speaking on documentation itself. Documentation is an integral part of an API. It is not an afterthought but a necessity. When you begin documenting an API, there are a few things to keep in mind. Generally, you should remember that consumers choose an API for the following reasons, as outlined by Mattias Biehl in his book, API Design.
- The API is easy to use.
- The API is easy to integrate.
- The API is well-documented.
- The API is easy to get started with.
In this article, we will address these principles through the lens of documentation. Technical writers in an organization may not have a direct influence on the API build. Still, they have a direct impact on the presentation of the API to the consumer, internal or external to their organization.
A technical writer can make or break the way that the API is perceived - does it look too complicated? Is it simple to learn? Will it be a challenge to use this API to empower my organization’s goals?
Only one of the four principles listed above appears to have to do with documentation. But, all of these have to do with how the API seems to the consumer. Documentation can make the API easier to use, easier to integrate, and easy to get started with. So documentation is paramount to the success of an API.
The point of an API is its useability. If there are no instructions on how to do this, the API is relegated to usage by those who spend more time learning the API based on trial and error, or who built it. Now that’s not very user-friendly.
We won’t go in depth about design-first principle, but that’s the philosophy we use when creating new APIs. Design-first principle means that planning is paramount; and we finalize a Swagger file before we begin building. We do this in order to prevent costly mistakes later on.
Here at DISQO, we use Slate for our API documentation. Slate is a three-column layout with the following type of content: table of contents in the left-most column, narrative form request information in the middle column, and code samples in the right-most column. We’ll refer to the content in this context to better illuminate how documentation can affect the ease of use, ease of integration, and ease of getting started with.
Our Audience API is built on Slate documentation and features a table of content, a primary narrative content, and a code sample column.
Let’s work with the three reasons people choose an API. These don’t initially appear to be directly related to documentation, but we will see that they are. We’re going to go through them to highlight how documentation can address the point.
The API is easy to use.
You can convey the idea that your API is easy to use in a variety of ways: have clear organization, highlight succinct information, and use clear, accurate code samples.
Have Clear Organization
Clear organization is intuitive. It makes it easy for a developer to land on the documentation and find what they are looking for without clicking around much, or using the search bar. The table of contents should outline the parts of the API clearly. At DISQO, we generally abide by the following structure. You may refer to our Audience API documentation as you look through this list to get an idea of how we use this structuring in a real-life example.
- API Overview
a. Narrative introduction
b. Base URL
c. Requests
d. Responses
e. Authentication
f. Errors
- Endpoint
a. Object reference
b. POST request(s)
c. GET request(s)
d. POST and PUT request(s)
e. DELETE request(s)
- Supplementary and reference information
Succinct information tells you everything you need to know and nothing that’s going to make you ask additional questions. APIs typically have complexities, so it’s imperative to reduce the API down to the most pertinent information that first allows a consumer to make a successful request, thereby increasing their confidence in the product.
At DISQO, we present the API in buildable components, accompanied by a full example. The developer has the option to seek out the code sample directly or refer to the elements that make up the request. This side-by-side information further shows to the developer that there’s no mystery to the API.
Extraneous information that doesn’t get the developer to a successful 200 or 204 response belongs in narrative form or a table. There is no more significant indicator of ease of use than for the developer to be met with success, even if the request is not quite precisely what they are planning to use in their application. Reduced down, we promote developer success by enabling them to make a stripped-down request before adding complexities.
Use Clear, Accurate Code Samples
Clear and accurate code samples provide developers with a clear foundational understanding of the API. Because of this, we are cautious about the values that appear in our sample code. Some general rules are that code samples should show how a value should look. For example, rather than write a string value as “string”, we would choose a string value that is likely to be submitted in the request. Even if we do not have an exact value that is likely to be sent in the request, it is better that we come up with a sample scenario rather than choose a random, nonsensical value.
We often see code samples, especially in beginner tutorials that include misleading and thereby distracting values. Be thoughtful about dummy values and avoid using values that could be interpreted as a part of the required values to pass. Additionally, never fabricate values like base URLs.
Technical writers should test all code samples while working on the documentation. It is not enough to assume that a request will result in a successful response. Technical writers can be very successful at breaking APIs during the documentation process.
The API is easy to integrate.
Documentation best communicates that an API is easy to integrate through these methods: explain what the consumer contributes, provide comprehensive data where needed, constantly preempt consumer questions, and iterate on the content.
Explain What the Consumer Contributes
An API is easy to integrate with when the consumer knows what they need to contribute to get the results they want. There needs to be a clear distinction between the two parts coming together. For example, in our Audience API documentation, we have a section in Integration Flow called How it Works, which shows that the API consumer should have a project management system for the integration to work. Now, this section is targeted more towards a marketing and product manager. But the code has its own ways of speaking the requirements that must be brought in for the integration to succeed.
The developers using the API documentation will need to know more granularly what data they should provide the API for the integration to work. We do this in our API documentation through our object reference sections. For example, in our Audience API documentation, we have a section called Projects for our projects endpoint. The first part of this section is called Project Object. Here, we outline all of the fields that appear in the Object, including the field type and a detailed description.
Based on this detailed information, the developer can discern what information they need to provide. They are also able to learn more about how we deal with the data that they give us.
Provide Comprehensive Data Where Needed
In this article, I have emphasized the importance of succinctness and providing just enough information to enable developers to gain success in using the API. Now, I will address the times when it’s appropriate and necessary to provide comprehensive data. Documentation should provide developers with a means of running requests, and it should also be a full-blown reference.
For example, the DISQO Audience API has a significant amount of additional information for developers. We provide this information in two forms in the Slate documentation. If you look at the Questions Library section of the Audience API, you will see that we front-loaded downloadable links to the Questions library as well as a long list of Vehicles. If developers want a quick reference without having to download and search through the files, we display the Questions Library as a long table.
We link to this Questions Library from various parts in the document as needed. Organizing the content in this way allows us to avoid repeating data or peppering data throughout the endpoint sections.
Preempt Consumer Questions and Iterate on Content
The responsibility of a technical writer in relationship with API documentation is to anticipate questions, keep it up-to-date, and to subject the content to consistent iteration. Documentation is a living document, even if the API itself does not change. A technical writer should be receptive to feedback, and in fact, they should encourage it. At DISQO, our open communication enables us to give and receive feedback on all facets of the products that we build and maintain.
While creating our documentation, technical writers at DISQO are encouraged to ask pointed and direct questions about the API they are documenting. We continue to ask questions and experiment directly with the API until we have a deep understanding of how it works. Additionally, we handle edits to documentation as they come in; they are not put off. This prioritization shows that we highly value feedback and take steps to show through our actions that we abide by this philosophy.
The API is easy to get started with.
DISQO’s technical writers have a significant impact on how consumers interpret how easy our API is to start with. We do this by keeping narrative skippable, giving developers instant feedback, and front-loading vital information.
Keep Narrative Skippable
Documentation can quickly become incomprehensible, especially when dealing with complex APIs. Because of this, it’s necessary to keep narrative short and skippable. There should be nothing in narrative form that prevents the developer from gaining a successful API response. The narrative should serve the purpose of introducing the endpoint. After reading this narrative, the developer, product managers, and other product consumers should be able to explain what the endpoint does in human-understandable terms.
Are you able to strip down the documentation to code samples and request requirements, and for it to still make sense to a developer? If you rely too heavily on narrative explanations, the information gets buried.
Give Developers Instant Feedback
Documentation should give developers a sense of confidence about using the API. The better way to do this is by enabling our API consumers to receive a successful response. Then, it’s the technical writer’s job to direct developers immediately towards simple requests that can be run unhindered by complexities.
Slate has been a useful tool for alleviating developer confusion since it displays three types of information: the clickable table of contents for navigation through the documentation, the main body containing narrative form descriptions of the requests, and the code samples. If a developer is able to click an endpoint and see a code sample quickly, they are able to run it. Technical writers should enable them to glance at the section and understand what the request looks like and how to find additional information if they need more.
Another way that we encourage developer success is by providing an importable Postman collection. Developers can click on the Run in Postman button and quickly start running their requests through this third-party API request application.
When writing information, it is critical to front-load vital information—front-loading breaks down the barrier between the developer and the product they are using. Astute technical writers have developed the ability to recognize what information is going to get a developer to succeed quicker and with fewer hiccups.
We front-loaded this very article with the takeaway of this article - documentation has a tremendous impact on making an API easy to use, easy to integrate, and easy to get started with. Documentation is not an extra. It’s an integral part of an API. Documentation makes or breaks a consumer’s experience and either enables or frustrates the developer.