APIs – The Magic Fairy Dust Inside Your App

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.

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 me).

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. You OK with that?”
Twitter: “Hrm. 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:

JSON:

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

XML:

<?xml version="1.0" encoding="utf-8" ?>
<Update>
  <Status>"This is a Twitter post"</Status>
  <Latitude>37.222</Latitude>
  <Longitude>-82.1234</Longitude>
</Update>

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.

Your Assignment

From now until my next post, spend some time on searching for things like “Facebook API” or “Twitter API.” Every big platform has an API and accompanying documentation. Read through the introductions for a few of them. You’ll see a lot of stuff that will make no sense, but you’ll also be able to understand more than you think.

In our next article, we’re going to cover how a request and response works in more detail. On the horizon are thrilling topics like the difference between push and pull, and how you read API documentation.

Stay tuned, this is going to be good!