APIs – How to Read and Understand Documentation

In the first article in this mini-series on APIs for the untechnical, we introduced the building blocks of how APIs work. In this article, we’re going to talk about how you read API documentation to understand what’s possible with a particular API.

Here’s a quick review of what we’ve covered so far:

  • An API a series of messages that an application or platform agrees to exchange
  • The message exchange is governed by a protocol, which is a fancy word for a kind of contract
  • Modern applications typically use the JSON format for messages, though some also support XML

We’ll continue with the example in our first article 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:

 

Twitter docs

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 in to 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 in to 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:

Screen_Shot_2016-04-07_at_2_45_33_PM

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.

We’ve just scratched the surface in this article. As we progress through this series, you’ll get introduced to different kinds of APIs and have a clear understanding of how they actually work in real life.

Your Assignment

Review the documentation for the Twitter and Facebook APIs. As you review the concepts, write down a list of questions that you can ask your developers. Then, schedule a 30-minute meeting with one of them to answer your questions. If you don’t yet have a developer to talk to, ask me.

In our next article, we’re going to talk about how you exchange messages with an API using some real-life examples.