What are APIs and why do they need special documentation?

An API is a set of custom commands

The term application programming interface (API) describes software that allows other software to interact with it. When an app includes an API, other apps can make requests for information or actions programmatically.

To accomplish that, an API has a unique set of commands and options that can be used to access whatever services are available. Depending on the API, the command might retrieve data, or write data, or perform a set of steps like reading, writing and processing data.

This site is mainly about web APIs, the kind that use HTTP or other protocols to provide functionality across the web.

Why APIs: coffee buying example

As an example, think about a web site where you buy a pound of coffee from a coffee roaster in another city.

The coffee site has a payment area where you enter your billing address and a shopping cart filled with goods that you want to buy. Both of these represent API services that exist on different servers from the one that delivers the web page to your browser.

The payment information that you punch into the website goes to a service that can securely process the payment, and since the coffee house is a smaller company, let's say the payment service is run by a third party that specializes in secure payments. That means the web page contains code that will talk to the payment service through an encrypted channel and then complete the sale when the payment service confirms that payment has been made. The merchant receives payment but does not need to see the card number that you used to make the payment -- in fact, they might not want to see it or store it for security reasons.

The shopping cart information is directed to a different service, which stores your order, the shipping address, and whatever other data is relevant to the merchant. Let's say the API that runs this service is also run by a third party, a company that helps small merchants set up an e-commerce site. In addition to collecting your order, this service has another interface, a web site for showing and printing all the current orders so they can be packed and shipped; that's a completely different kind of functionality but provided by the same API that stored your order.

What these APIs have in common is that they are software that provides a service to other software. When you punch your information into the merchant's website, a script (a program) in the page transmits the information to the API service. This makes it possible for each of the APIs to process thousands or millions of transactions every day, regardless of where merchants or customers are located. The APIs never sleep.

The existence of APIs allows developers to focus on smaller areas of functionality: one team designs and builds merchant websites, another team focuses on payments, a third team on shopping carts. The coffee customer and the merchant get more usable web sites and services because of the division of labor.

Why the documentation is important

Think of the API commands as an invented language, for talking to one specific application. For example, the payment service would have its own very specific commands and syntax for transmitting the payment information about a single payment.

The API reference documentation is like a dictionary for the language that the API speaks. The developer who built the merchant website, would have to consult the documentation for the payment API and the shopping cart API, so that the website would communicate data in the way that each API expects.

APIs are tremendously useful and powerful, but without documentation they would be impossible to use, because each has its own particular way of communicating requests.

APIs typically only accept requests sent in the correct way. For example:

• The request must be sent to a specified URL.

• It must correctly use commands from the API reference and no additional or unnecessary code.

• The API might require that when a certain command is used, the user must provide certain data or must include one of several attributes that clarify the command to make the request complete. For example: A command to record a purchase with the shopping cart service, would have to require an inventory number indicating what is purchased. Otherwise the transaction cannot be completed.

API documentation helps developers to make use of an API as quickly and painlessly as possible by providing answers that cannot be derived from the API itself.

• The most important documentation is the reference section, which explains every command and option available and how to use them.

• A quickstart (or a more extensive guide) reveals the set of steps necessary to get results from the API, when users have to send a series of requests to different URLs to get the result that they want.

• An overview (the chapter most often omitted from the documentation) explains what the API is used for, what problem it is supposed to solve, and how it works.

Final thoughts

• This site will tell you how to document APIs, including what to include, how to structure the information, and how to write effectively for developers.

• See the resources page on this site for other websites, classes, and additional resources that explain APIS and how to document them.