APIs – Getting Under the Hood

In the first article in this mini-series on APIs for the untechnical, we introduced the building blocks of how APIs work. In our second article, we talked about how you read API documentation, and looked at a specific example using the Twitter Status Update.

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
  • You can figure out what’s possible with an API by reading the documentation provided by the application

Now that you’re sufficiently refreshed, let’s dig in to an actual Twitter update request and see how it works.

Push and Pull

APIs generally operate in one of two ways: Push and pull.

Push

A great example of a Push API is Push notifications on the iPhone. When someone sends you a message over iMessage, Apple figures out whether or not you’re online on any device and then “pushes” the notification to any and all devices. Your phone is sitting there listening for any new messages, and when it gets one, it shows it to you. Application APIs work more or less the same way. Let’s look at another common example, that of getting notifications in Slack.

Here’s a screenshot from an integration I built to Slack:

Screen_Shot_2016-04-12_at_8_59_05_AM

 

Slack has a really nifty API that allows any application to push data into a slack channel using something called a Webhook.

You know how restaurant kitchens have an in door and an out door so that people don’t run into each other? A webhook is the in door. It takes data in, but does not (generally) send data back out. Just like with the Apple example above, Slack sits there waiting for someone to send them a message. When they get the message, they figure out who’s supposed to see it, and what channel it’s supposed to go to, and they send it there. Pretty cool, eh?

Pull

When you need to get data from another application, for example a list of a user’s Tweets, that’s done using a pull API. It’s just what it sounds like. Your application shows up at the other application’s door, asks for some information, and leaves with the response.

A Simple Request

Enough theory. Let’s look at an actual request and response.

Here’s what a request to Twitter’s Status Update looks like (pulled from our first article):

JSON:

{
  "status":"This is a Twitter post #test",
  "lat": 37.222,
  "long": -82.1234
}

When we send this message to the Twitter API on behalf of our user, it will create a new update in their Twitter feed that says “This is a Twitter post” with the hashtag #test, and will tag it to the geo coordinates 37.222 latitude, -82.1234 longitude. As you can see, when you put all of this together, it all starts to make sense. An API allows you to do things behind the scenes that would normally require a user interface. We could have sent our user over to Twitter to do this themselves, but when we integrate to the API, we take care of it for the user and make a better experience for our user.

So, we’ve sent the request. Now what?

A Simple Response

Twitter’s API will tell your application what went right or wrong using a response. Let’s look at a small section of the response, and you can look at a full response on the documentation page if you want to see more.

{
  "created_at":"Wed Apr 05 00:37:15 +0000 2016",
  "hashtags":[
    {
      "text": "test",
      "indices":[ 24,29]
    }
  ],
  "id": 243145735212777472,
  ...
}

The actual response has a TON more data, but let’s look at just these few to get a sense for what we see in a response:

  • created_at is the date and time that Twitter created the message on their system.
  • hashtags gives us a list (called an array) of all of the hashtags in the message, and their position in the text. In this case, our #test hashtag appears at position 24 in the text
  • id is the internal ID that Twitter assigned to the message. If you’ll notice, the value for “id” is not surrounded by quotes. The reason for this is that the ID is a number, not text.

What would have happened if we’d sent bad data to Twitter? For example, let’s say our credentials were invalid or we put some invalid characters in the message. In this case, Twitter would respond with the proper error code and perhaps an error message telling us what was wrong. It’s up to our developers to handle that error properly and tell the user how to fix it.

Going to the Library

One of the great things about the modern programming era is that there’s so much software available for free.

When we want to talk to Twitter’s API, we can build an integration from scratch OR we can use something called a helper library that’s already been built. Nearly every platform out there that provides an API will also provide helper libraries in the most popular languages. These helper libraries allow your developers to get integrated much more quickly because they don’t have to do all of the work from scratch.

Here’s a link to the Twitter helper library for NodeJS, just to give you an example. These libraries can be built by the company themselves, or by other developers who’ve done the work already and choose to share their work for free. How cool is that?

As an aside, if your developers build new libraries for APIs, I would highly encourage you to open source them and share them freely. Give back to the community from which you are most certainly going to benefit in the future.

A Final Word

We’ve focused most of our attention on your application talking to another application using APIs. The reality is that, when built properly, APIs will exist throughout your application as well. For example, when your application saves data to a database, that’s using an API. When your user interface displays data to a user, that’s using an API.

Because an API is a contract that governs how data moves in and out, creating well-defined APIs inside your application forces your developers to be more disciplined in their approach to how the application is built.

Just Remember

We’ve covered a ton in these last few articles, and I don’t expect you’ll be an expert in understanding all of the nuance of APIs by now. However, I hope you have a better sense of what it takes to integrate to an API, and that when your developers are talking about how all of this works, you’ll be able to join in the conversation and not be lost.

Don’t be intimidated by talk of APIs or looking through the documentation. In the end, APIs are just one more way to move information around either between applications or even within an application. There’s nothing magical happening at all.

Your Assignment

Review the API documentation for three or four applications you use every day. It could be Twitter, Facebook, Slack, or even Salesforce. Then, think about scenarios where your application would interact with each of them and see if you can map data from your application to one or more of the API methods on these other platforms.

You could even use a spreadsheet and have a column for your data, and a column for the API method on the other application. Do whatever works best for you, but wrestle with it for a bit.

If you need more help, or want to understand more on the topic of APIs, give me a shout and I’ll help you out.