Understanding API Documentation

Goal: By the end of this checkpoint, you can understand and use API documentation for your development purposes.

Wouldn’t it be cool if, instead of having to build everything your app needs, you could use all of the tools that your other fellow app builders have built? What if your developers could, with a few lines of code, use all the features of Twitter, Facebook, Google Calendar, and all of the other apps your users already know?

The good news, as you’ve no doubt guessed, is that you can. These other applications make all of their goodies available to you via something called an API, or Application Programming Interface. While that sounds really dull and boring, APIs are a lot like magic fairy dust: You sprinkle a few in, and poof! Instant capability.

By the end of this next series of posts, you’re going to know how APIs work, how to read API documentation like a boss, the difference is between a push and a pull API, and a whole lot more.

Key terms

  • Parameter
  • Query string
  • Endpoint

What’s an API?

In untechnical speak, an API is like a secret door into another application (yes, I know it’s a different metaphor, but hang with us).

Let’s say you wanted to let your users create a new Twitter post. You could either make the user copy and paste something from your app over to Twitter and create the post (inspiring visceral hatred of you and your product), or you could use the Twitter API.

When your app uses the Twitter API, it goes something like this:

Your App: “Hey, Twitter. I’ve got this user here who wants to post something in their feed. Are you OK with that?”

Twitter: “Hmm. I don’t know. Let me check the super-secret decoder key you gave me against my ledger. ”

Twitter: “Yep, you’re ok. I’m opening the door.”

Your App: “Woohoo! Here’s the post I’ve got for you. Git ‘er done”

Twitter: “You betcha. It’s done. Now get outta here!”

APIs are just a series of messages that two applications agree to exchange.

At a high level, that’s all there is to it. Of course, we can’t stop there because, well, that would be boring and I promised you more.

Speaking the Language

The messages that APIs agree to exchange are governed by something called a protocol. A protocol is nothing more than an agreed upon way to communicate, just like a diplomatic or espionage protocol. The protocol for an API says “Here’s what I’m expecting, and the order I’m expecting it in.”

If you don’t follow the protocol, the exchange of messages will fail, just like if you were a spy and didn’t use the right pass phrase when meeting someone in the elevator to exchange the briefcase. I watch a lot of Jason Bourne movies.

Generally, all message protocols have a request (what you want the API to do) and a response (what the API actually did).

Your developers would then look at the response and figure out if the request they sent actually worked. They would take the next appropriate action based on the response.

The Medium

Most APIs use the internet as the channel to transmit messages back and forth. It’s not always true, so don’t have your developer yell at me if you’re using an API that doesn’t. You could, in theory, have a direct connection to some system that doesn’t use the internet, but that’s pretty rare these days.

The Message

Messages can be literally any format, but the two most common formats are JSON and XML. JSON stands for JavaScript Object Notation, and XML stands for Extensible Markup Language. Enough developer babble.

Here’s a quick example of each, creating a fictitious post to Twitter:



  “status”:”This is a Twitter post”,

  “lat”: 37.222,

  “long”: -82.1234




<?xml version=”1.0″ encoding=”utf-8″ ?>


  <Status>”This is a Twitter post”</Status>




The Twitter API doesn’t actually support messages in XML format anymore, but you hopefully get the idea.

JSON is far and away the most popular and most heavily used message format in modern APIs.

Let’s pause here and recap what we’ve learned, and what we’ve got ahead of us.

Just Remember

APIs sound really complicated, but they’re really just a series of messages that two applications agree to exchange using a pre-defined agreement called a protocol. Most APIs use the internet to exchange these messages, and these days most messages are in a format called JSON.

Let’s continue with the example of a user wanting to post an update to Twitter from your application.

We’ll be using Twitter’s REST API documentation found here as our reference.

Methods to the Madness

When you first open any API documentation, you’ll usually get an overview much like Twitter provides, and you’ll see a list of things you can do with the API. The things you can do are called methods in programming vernacular. For example, a developer might say “I’m going to use the status timeline method to get a list of user posts”. Here’s a screenshot:

You’ll notice that beside each of the method names (statuses/user_timeline, statuses/home_timeline, etc.) there is the word GET and POST. In other APIs, you might also see PUT and DELETE. What do those words mean? Without getting overly deep, here’s what you need to know:

  • A GET method lets you retrieve (or get) something
  • A POST method lets you create something new
  • A PUT method lets you update something that already exists
  • A DELETE method lets you remove something previously created

Let’s dig into the documentation. Have you ever had more fun?

The Overview

Most documentation will provide you with an overview of how to connect to the API, and the rules that govern it’s use. For example, if we look at Twitter’s overview, we’ll see that they have the following sections:

  • Rate limiting – How much you can use the API in a given period of time, typically broken down into requests per chunk of time. e.g. 15 requests per second
  • Authentication – How you get connected to the API and successfully share your credentials
  • Acceptable Use stuff – How to upload media, and how to handle things like sharing NSFW images or content

This is where all developers start when they dig into an API, so spend some time reading through it. It’s OK if you don’t understand it all.

Method Details

Once you’ve read the overview, you can dig into the details for a particular function you’re interested in and see how it works.

Let’s take a look at the documentation for the Status Update Method. This is the method you use to create a Tweet.

You’ll see there’s a lot of information to digest here, and this is just one method. The Twitter API has probably 2-300 methods across all of the different capabilities. Generally an API method will have the following things in common:

  • The URL you use to connect to that method, often called a Resource URL or Endpoint
  • The parameters the method can accept (often times there are both required and optional parameters)
  • Examples of both the request and response

While some of this may seem like Greek, if you read through it you’ll be able to make sense of more than you think. For example, our Status Update method has only one required parameter, a field called ‘status.’ You can see that here:

If you scroll down a bit further on the documentation for this method, you’ll see additional optional parameters like lat and long that can also be a part of this message.

Just Remember

With a basic understanding of terms we’ve talked about here, you can begin to evaluate the documentation of different services and understand how your app would communicate with them via their API. This is incredibly useful for you as a product owner, as you can have your own opinions about possible integrations before talking to your developers.

Few more Examples of API Documentations

Let’s look at some examples of great REST API documentations. For many years, two names continue to come up when discussing API docs: Stripe and Twilio. Stripe and Twilio have based their entire companies on developers successfully integrating, so they’ve placed a lot of attention on their API document.

Stripe’s API reference has nearly become a standard for its completeness and browsability.

Each operation on an endpoint is described in human-friendly terms, along with the arguments developers pass to Stripe. Finally, a copy-paste request is shown, with an example response provided below.


Twilio’s guides are notable for both their programming language coverage and how they walk you through step by step.

Twilio keeps the code visible while you read the description of what’s happening and how to customize it for your needs. You can click through a step at a time or browse the code samples, which are described the way a developer would use them.


Heroku’s examples are not an API, but worth mentioning for how well they cover the cloud platform’s supported programming languages.

Each example is also accompanied by a guide, but what’s notable is Heroku walks you through cloning a git repository. By helping developers start with a complete app in their chosen language, Heroku quickly points would-be customers to a quick success.

One of the most important jobs of documentation is to help someone completely unfamiliar with your API. At the same time, you want it to remain useful for the developer who has already used your API. Of the three types of documentation, the reference most needs to remain relevant throughout a developer’s interaction with your API.

Here are a couple of videos you can watch to consolidate your learning and see things in action!