What is an API?

API is short for "Application Programming Interface." An API is a set of programmatic instructions that allow one program, or part of a program, to interface with another program. It’s the set of rules that these programs should use to communicate. Sometimes, they're small (within the same program); sometimes, they're big.

In either case, they function as both a contract and a translator. As a contract, APIs set the terms for what kinds of inputs can be given on either side and what kinds of outputs either side can expect in return. As a translator, APIs help 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 Programming 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 you what an API is, you can explain it to them without them going bald, too. Below, you'll see a few of our outstanding APIs, or read on and see what an API is and what you should look for when researching them.

Try our Address Verification API	Try our Autocomplete API	Try our Geocoding API
Try It Free	Try It Free	Try It Free

• Using examples to understand APIs
• An in-depth look at APIs
• API features
• What defines a good API?
• Documentation
• Meets expectations
• Clear error codes
• Easy to test
• Easy to use
• Fast
• Significant uptime
• Redundancy
• Performance monitoring by a third party
• Scalable
• Backward compatible
• Why care about APIs?

Using examples to understand APIs

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.

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 funds 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 already done all the hard work—years of schooling and practice in his field- and has 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 example highlights 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’ll need a way to connect to them that doesn't mess with their system, provide go-betweens.

API features

APIs have a couple of important features that define them:

1. 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.
2. APIs 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.
3. APIs translate. If you've ever wondered why your Xbox disk won't play on 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 have 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?

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 documentation quality often greatly impacts the ease of the API's use—the clearer and more extensive the documentation, the smoother the tool's operation.

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 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, and 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 blank page 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 kinds 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 to have 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," so that good programmers can fix the problem.

Easy to test

Good APIs will offer a way to test the interface before committing to its use. This is important because a programmer can know exactly what they’re getting and how to use it. If you want X, you should be able to get X without creating problems. 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 (which sometimes also costs money) and then starting the process 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 open it back up every half-hour for 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 and receiving output as short as possible. After all, if an API is too slow, it becomes as cumbersome as not having one at all. Testing an API for its turnaround time should be crucial to 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 (when the API isn’t callable) 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, ensuring 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, redundancies will cover most downtime issues.

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 third party tests the API to make sure it's running properly and then lets potential customers know that the API is reliable.

Scalable

Some jobs can only be done by one person. Leonardo's painting of the Mona Lisa is an example of that. 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 add 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 that the code 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 API clients being notified with adequate time to prepare for the changes.

Why care about APIs?

A good API brings great power, versatility, and functionality to the existing code of a program, application, or website. They increase the speed and reliability of communications between programs. Whenever 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.