What is an API?

API is short for "application program interface". An API is a set of programmatic instructions that allow one program, or part of a program, to interface with another program. Sometimes they're small (within-the-same-program small); sometimes they're big. In either case, they function as both a contract and a translator. As a contract, it sets the terms for what kinds of inputs can be given on either side of the API, and what kinds of outputs either side can expect in return. As a translator, it helps the two processes speak a common language so the exchange can be made.

If you're reading this article, then you've likely been pulling your hair out. Most information about APIs is complicated and wordy. Application Program Interfaces, or APIs, can be difficult to understand if they're not explained properly. So we're going to do our best to explain it well—hopefully well enough that if someone asks youwhat an API is, you can explain it to them without them going bald.

Let's use an example to conceptualize this. Consider the power outlet your computer is plugged into right now. That outlet is an interface—it allows your power cord to access the power being supplied from the power plant. That outlet puts the electricity into a format that the computer can use. Now consider how there are different kinds of outlets (phone, internet, coaxial cable, 240 volt, European outlets) that each interface (there's that word again) with different sources. That's a little like an API: it brokers communication to a source that someone wants to access.

If you want to know more about APIs and how to tell if you've found a good one, keep reading.

An in-depth look at APIs

For a little bit of additional clarification, let's look at a more in-depth example. Imagine you have the (unfortunate) need to deal with the legal system. You need to be able to appear in court, or file something to a judge, but you have very little experience in that field. You have a couple of options if you want to get the outcome you're hoping for. First, you could go to school and study to be a lawyer. You have the capacity to learn and (let's pretend) the means to pursue it. But it takes a great deal of effort, and much more time than you have available to you.

Second, you could do some study by yourself—brushing up on your legalese, maybe watching a lot of courtroom dramas, or even sitting in on real trials and hearings. This doesn't necessarily instill in you the confidence that you've trained with the right information, or that you're prepared for real-world experience.

Then there's the preferable solution: hiring a lawyer.

The lawyer has done all the hard work already—years of schooling, practice in his field, intimate knowledge of the laws and how they can help you. You work with the lawyer to properly interact with the court system to get the solution you're looking for. The lawyer takes your instructions and requests and turns them into legalese, which is then used to pursue your interests with the courts. Then when the courts respond, the lawyer translates that legalese back into layman's terms so that you can understand it.

This long-winded example is like how APIs work. APIs are building blocks or open-ended processes designed to allow something new to interface with an existing system, program, or process. Like the court system or the power plant, there's an infrastructure we want access to, and they, knowing we will need a way to connect to them that doesn't mess with their system, provide go-betweens.

There are a couple of important features that define APIs. First, APIs make the rules. If you're using an API, the API determines what you get and how you get it. Much like you can't plug a power cord into a phone outlet, input and requests given to an API must meet the API's specifications.

Second, API's don't do anything on their own. Their value is only realized when a secondary program (most often called a "client") accesses the API's functionality for use within its own program. There's really no limit to the number of client programs that can be tied in (at least as far as the API's infrastructure can handle, but we'll talk about that in a bit). For instance: many blogs and websites have installed a "Share" button that actually ties into the Facebook API. The "Share" button can be installed on any number of websites, but they all aim back to the Facebook API. Facebook built that API and made it available so that anyone who wanted to tie in could do so. But without those clients, the API would be completely pointless.

Third, APIs translate. If you've ever wondered why your Xbox disk won't play in a PlayStation, you've run into the problem at the core of this topic. Computers are like people: they speak in a lot of different languages and dialects, and sometimes getting them to communicate can be hard. Sometimes the program an API connects to will speak in a different language, or even with its own unique syntax, and outside programs won't be able to understand it. So APIs bridge the gap, turning acceptable inputs into something the source can process, then turning the source's response into something that the outside program can understand.

Now, hopefully, we've covered what an API does thoroughly and clearly. There's still the matter of how effectively it does it, and therein lies the difference between APIs that do their job well and APIs in name only. Let's take a look at some particulars.

What defines a good API?

Just like any other product or service, different APIs have different levels of quality. Knowing what to look for in an API before trying to integrate one is important. So let's break down some of the things that, from a programming perspective, make an API worth using.

Documentation

"Documentation" is information that the API creator provides to the programmer, explaining everything from how to make the API work to why it might not be working and what to do about it. The quality of the documentation often has great impact on the ease of the API's use. The clearer and more extensive the documentation, the smoother the operation of the tool.

Meets expectations

Do you know exactly what you want this API to do for you? APIs tend to be very specific in what they will and will not do. If you have not clearly defined your problem before you start looking for an API, you will likely get lost in all of the various options and documentation of each API. What's worse, not knowing what you expect from an API—or what its documentation promises it does—means there's no way to tell when it's off the mark. In short, first decide you need X, then find an API's documentation to see if it does X, then test it to make sure it doesn't give you Y instead. Knowing exactly what you want an API to do is critical to successfully evaluating any API.

Clear error codes

Along with good documentation, having error codes that make sense is an essential element of a good API. If you've ever mistyped a website's URL, odds are you were shown a page that was blank except for "Error 404." That's an error code, and while most of us don't know what that means or what to do about it, a programmer's job usually includes making sure those kind of things pop up as infrequently as possible. But sometimes it happens to them, too. Like when they're trying to use an API. When that happens, it's helpful for there to be clarification, either in the error code or in the documentation, that helps them identify the problem and fix it. Good error codes tell the programmer "It's broken, and here's why."

Easy to test

Good APIs will offer a way to test the interface before committing to its use. This is important so that a programmer can know exactly what he's getting and how to use it. If you want X, you should be able to get X—without creating problems rather than solving them. Dealing with an uncooperative API after it's been integrated means wasted man-hours, which of course costs money. There's also the issue of having committed to using the API (a thing that at times also costs money) and then having to start all over again with a different API.

Easy to use

Programmers can be very skilled at their job and, like everyone else, take pride in accomplishing hard things. But they still like it when things are made easy for them. They don't want to have to fight the program, or spend days rewriting code to make it work. They want to be able to read the documentation, tie it into their system, and have it running within the day—preferably within the hour. And they certainly don't want to be opening it back up every half-hour to do maintenance.

Fast

The speed of APIs varies widely. Your need for speed may also vary, from mission-critical to extravagant luxury. That said, a good API will strive to keep the time between entering input to receiving output as short as possible. After all, if an API is slow enough, it becomes as cumbersome as not having one. Testing an API for its turnaround time should be a crucial part of evaluation.

Significant uptime

"Uptime" refers to the time a program spends actually running the program. It's kind of like that sign in the factory: "X days since last accident"—you want that number to be as high as possible. Downtime can be a result of many things, including problems with the hardware (like someone fell over in the utility room, and unplugged all the servers), problems with the software (a bug or mistake in the code), or a multitude of other things. Higher uptime means that a company has done a good job of avoiding or quickly repairing these problems, making sure their services are always readily available to their customers. Failure to do so is often an issue with Redundancy (see below).

Redundancy

"Redundancy" means having backups. A good computer system has multiple redundancies in multiple locations to cover power outages, computer and server failures, and natural disasters. If they've prepared properly, most issues with downtime will be covered by redundancies.

Performance monitoring by a third party

Performance monitoring can be done both internally and externally, and is best used in tandem. But for companies looking at using an API, it's best to have an outside source that can verify that the API has a high uptime and that it's as fast as possible. By sending in requests as customers would, the 3rd party tests the API to make sure it's running properly, then lets the potential customers know that the API is reliable.

Scalable

Some jobs can only be done by one person. Leonardo painting the Mona Lisa is an example. Some jobs go faster when additional manpower is applied, like digging a ditch. That's "scalable," and good APIs are scalable. If demand becomes too high and servers get clogged, the API should be able to apply more servers to the problem to handle the extra traffic, just like adding extra shovels to the task of digging the ditch.

Backward compatible

This means that the creators of an API won't arbitrarily rewrite their own rules for communicating with said API. Any changes made to the API need to be backward compatible so code that you write against an API doesn't break without warning. Any necessary breaking changes are released as a completely new version of the API (at a different address), or the deployment is a coordinated event, with all clients of the API being notified with adequate time to prepare for the changes.

Why care about APIs?

A good API brings a great degree of power, versatility, and functionality to the existing code of a program, application, or website. They increase the speed and reliability of communications between programs. Any time you've seen a "Like" button, an embedded Youtube video, or a Google Maps insert on a web page, you're looking at the fruits of an API.

APIs make everything run smoother; a well-developed API can save countless man hours, and that kind of streamlining is always appreciated by programmers and business professionals alike. Whether or not you've recognized them when you've seen them in action, odds are you've been happy with or grateful for something an API has done for you.

So go ahead. Tout your newfound understanding of APIs. They're important, and you might just be a little more important now that you know what they are.