Note: If you’re reading Hack Writing via the RSS feed, you may need to resubscribe. The feed now contains the full text of each article, instead of an excerpt; some RSS readers (namely, Google Reader) have not been displaying the full text without resubscribing.

After Assuming the worst, I received several comments from readers asking, more or less, “What’s an API?” In this post, I hope to satisfactorily answer the question and to give you a sense of the documentation issues that surround APIs.

API stands for “application programming interface.” In practice, it’s the way one piece of software communicates with another piece of software. Although you might interact with a piece of software through a user interface (i.e., the part of an application on your computer, a web page in your browser, or an app on your phone that you type, click, or tap on), software typically communicate with each other by way of APIs.

For example, suppose you love Twitter, but you don’t want to go to Twitter’s website every time you update. Instead, you want a program on your computer to post to Twitter for you (known as Twitter “client”). It’s possible to write a program that, behind the scenes, goes to a web page, submits a form, and handles the response, but it’s a cumbersome and fragile proposition. What if the layout of the page changes? What happens if the wording of a confirmation message changes? How many clicks and keystrokes must be passed along? There has to be a better way.

And there is. Many web services and software packages provide an API. In the most general sense, an API is a specification. An API describes how other software can interact with it directly, bypassing the user’s interface. Frequently, APIs take the form of programming language bindings and software libraries that can more tightly couple two (or more) software programs. In our example, Twitter defines an HTTP API. Software that uses the Twitter API sends Twitter a specifically formatted chunk of text over the Web to ask for data. Practically anything that can be done by way of the Twitter website can be done with Twitter’s API: listing tweets, showing user details, or posting new updates.

For many software developers, particularly for those on the web, an API’s documentation may as well be the sole representation of the API, aside from directly interacting with it. Most web services are closed source, which is to say that the implementation of the service is not publicly available. Thus, for software developers who work with web services, the API documentation is the only official representation of the API they have. For a developer, it’s often the case that a discrepancy between an API’s documented function and actual use constitutes a bug in the API, whereas the maintainers of the API might regard it as a bug with the documentation. And ultimately, it’s the potential for discrepancies which introduce the challenge of creating high-quality API documentation.

API and documentation discrepancies can come from various sources, including:

• Various versions of the API
• Different formats for sending and receiving data (e.g., XML or JSON)
• Varying platforms (e.g., Mac versus PC or Desktop versus Mobile)
• New features
• Deprecated features

Each possible point of contention between documentation and implementation poses a question to an API documentation author: how do I describe to users how and under what circumstances this thing can or should be used? Moreover, it behooves the author to be accurate and clear; getting it wrong or inadvertently misleading readers can be as detrimental as an outright bug in the API’s implementation.

When it comes to API documentation, the stakes are high. An API’s popularity frequently depends on the documentation appropriately and accurately describing the API to developers who may use it. While a web service might have a powerful and useful API, if developers can’t understand what it does, it won’t be used. And that can cost an organization time, customers, or even overall success.