What Is API Documentation?

By Scot Marvin | Member

I’ve been writing API documentation for 15 years. During that time, I’ve seen a rise in API offerings. Companies are producing platforms that they hope others will plug into, using the platform’s API. API growth means more API documentation. And that’s a good thing for technical communicators.

In this article, I’ll address what an API is, what API documentation contains, the audience for this type of documentation, and how you can get started in this field.

What Is an API?

Sometimes software developers want their software to be used by another software application, instead of being used by a human being. Because the interaction will be with another software application, instead of with a person, there needs to be an agreed-upon way for the programs to interact. This language, and its inherent set of rules, is called an application programming interface (API). Essentially, an API makes it possible for software applications to communicate with each other.

The information exchange between your software and an API usually takes the form of a request and a response. Your software makes a request, using the API, and the other program sends a response back using the API.

Some APIs are used to exchange data between products that are external to one another. If you want to interact with Google or Twitter, you would use their API documentation as a reference for writing code to exchange data between your product and their products.

Other APIs are used to exchange data internally between services within a company or product. Both Windows and Android operating systems have internal APIs so that developers can easily write sub-programs that communicate with different parts of the system.

And still other APIs are used both internally and externally. Amazon Web Services has over 40 services that offer APIs for anyone to use. Amazon developers also use these APIs internally, so that the various services can communicate with one another.

Whether used externally or internally, APIs need to be documented so that communication can take place.

What Is API Documentation?

APIs are diverse in terms of language and functions, but what they share is the fact that the user sends a request and the API (sometimes) returns a response. The technical writer’s job is to detail what goes into a request, what form the request takes, and what data gets returned.

The structure of API documentation is varied but, in my opinion, a good API narrative provides readers with:

• syntax of each operation
• a description of what the operation does
• what parameters the operation takes, including default values, valid values, and type of data—boolean, string, etc.
• what data the operation returns
• error messages you might encounter using the operation
• examples of working requests and responses

This sounds like a lot, but all good code has the content already there. The API writer has to look, ask, and act like an editor to deduce content that is not in the code.

At its core, API documentation details information about code: the available commands, what each command does, and the parameters for each command. Traditionally, an API document describes one operation and how to make a request. This document is usually composed of tables filled with parameter names and accompanying values, along with sample code. Combine all the API documents, one for each function in an API, and you have produced an API reference guide. It’s basic but helpful.

But what about documentation for people who want to do more than just make a simple request? Most developers want to know how to string commands together and interact with input and output. Many writers produce developer guides that contain common use cases and tasks for working with an API, along with code examples.

Another type of API document, the user guide, contains content that’s not related to coding, but rather explains how to use an API’s associated command line interface or graphical user interface. These guides normally contain concepts needed to understand the API, deployment and configuration tasks, and best practices.

If a writer wants to lower the barriers for using the API—essentially helping anyone who owns a computer to use the API—he or she will create a “getting started guide.” This type of API document helps users understand the API by walking them through a set of tasks, after which they know more about the API operations and what they could do.

Some companies package these various API-related documents together and publish them as a software development kit (SDK). People using an SDK usually count on having other things included besides just API documentation. Normally an SDK includes working code and a test platform of some kind, along with the documentation.

Ultimately, readers of API documentation are looking for two things: correct information and working sample code.

Who Uses API Documentation?

In technical communication, we usually place audiences into three broad categories: end users, system administrators, and developers. I’ve come to believe that every reader of a technical document, whatever the document is, is really just an end user of some type. Some end users need information about how to create a new file in an application. Other end users need information about how to run a command in a terminal or command prompt. And other end users need information about how to write a program that exchanges data with another program.

End users of API documentation are usually developers, but there is API documentation for system administrators, too. System administrators usually look to API documentation to perform tasks that don’t need to be programmed but need to be used on an as-needed basis. Traditionally this has been with command line operations. For example, to set up a user in an account, the system administrator would run a command to generate a key pair so that the user could start making requests to the API.

A developer, on the other hand, might want to create a string of operations that run programmatically at certain times or in certain conditions. For example, when a request from one command is returned, a second command will then run using the returned values from that first command. In this case, a developer builds a workflow or a framework that uses the API functions.

Some APIs are meant for occasional commands, such as “backup my database at this point in time.” Others are meant to be used in a repeated and programmatic way, such as “when my Web server gets 80% busy, create another Web server and share the workload between the two servers.”

Who Writes API Documentation?

Folks in our growing industry who write API documentation often have titles like “programmer writer” or “senior technical writer.” Usually there are two paths to becoming a writer who documents APIs. The first path is the one taken by the writer who has written for a long time, has a great understanding of communication practices, and decides to start documenting APIs. This is the learn-code-as-you-go path.

The second path is the one taken by the developer who has decided to concentrate on writing. This is the learn-writing-as-you-go path.

This article is for the first path sojourners. If you’re interested in documenting APIs, you would be best served by the following general rules:

• Learn to read code. And by that, I mean learn to read code, not necessarily write it. Look around and read the comments in the code. See if you can make sense of what the code does. Writing API documentation requires some familiarity with a programming language, but you don’t have to be a developer. You have to understand what to look for in code, sure. But mainly you need to understand what the code does, why it was written, what the intended purpose is, and who should use it and in what situations. This last part is the most important, because that’s the part that readers will keep going back to your documentation for. Consider getting an introductory book about the programming language for the API you’re interested in.
• Learn common API technologies. Normally, the API message content is either in Extensible Markup Language (XML) or JavaScript Object Notation (JSON). The format of either file type is pretty easy to comprehend, but it’s good to look into an introductory book about these. The API content is delivered using Representational State Transfer (REST), or possibly Simple Object Access Protocol (SOAP). You can learn about these quickly using a good book or a search on Google.
• Look at a few different types of API documentation. It’s always good to see what is available. Check out the documentation for Amazon Elastic Compute Cloud documentation (https://aws.amazon.com/documentation/ec2/), Google Cloud Storage XML API (https://developers.google.com/storage/docs/xml-api-overview), and Twitter (https://dev.twitter.com/docs/api).
• Learn to swallow your pride.Ask a subject matter expert what’s going on in the code. There are occasions when even the best developers have to consult one another to figure what some code does. If it’s not always clear to them, it won’t always be clear to a writer. But remember to be prepared first. Don’t waste developer time because you didn’t do your research first.
• Grow your curiosity. Play around with the code with a toolkit or a test harness, if such a thing is offered for the API. Send a request using the API and see what happens.

It sounds like a lot of work and a lot of things to learn, but it really is pretty simple once you get started. API documentation is a growing area in our craft. I encourage you to check it out and see if you like it. We need a lot more great writers.

Scot Marvin (scotmarvin@gmail.com) writes API, cloud administration, and system administration documentation for Eucalyptus Systems, a company that makes private and hybrid cloud software that is compatible with Amazon Web Services. Scot lives in Corvallis, OR. When he’s not chasing his toddler and teenager around, you can find him on Twitter (@scotmarvin) or on the Web (scotmarvin.com).