For those of you who know me, I’m an API guy. They’re kind of my thing. I blog about them regularly, give talks at conferences, and even talk about them in podcasts.

They are the building blocks of software. The heart of integrations. The keys to our future. We need to spread the word about how great they are. But not everybody understands technical talk.

Every article I’ve read about APIs first describes them as an Application Programming Interface. While that might be what the acronym stands for, that doesn’t go very far when it comes to explaining what it actually is.

Super high level, an API lets you do things in software that you may or may not be the creator of. To understand this a little further, let’s bring in a concept everybody knows: tv.

Give Access to Basic Functions

A tv has well known and established controls:

• Power on and off
• Volume up and down
• Channel up and down
• Change Input

Every tv you purchase today will have these controls. You can do all of these commands via a tv remote. You can use the remote that comes with the tv or you could purchase a different one instead.

The remote control will use the established commands to control the tv from the comfort of your couch. You just point and click.

This is how APIs work.

A piece of software has known and established features (the API). Software companies provide documentation on what features are available and how to use them. Integrators build software of their own to communicate with the API to make it do what they want.

In this metaphor the software is the tv, the API is power on/off, volume up/down, etc.., and the integrators are the tv remote.

Building Against Known Standards

One of the primary goals of any system is to have a low barrier to entry. Companies want to make it as easy as possible to use their products so consumers have enjoyable experiences, tell their friends, and spread the love.

The easiest way to provide a quick learning experience is to adhere to standards put in place by the industry.

In our tv example, volume up and down are universal. A tv will expect a certain code to be sent by a remote and when it picks up on that code it adjusts the volume. Same with changing the channel or turning the power on and off.

Some tv vendors will use proprietary codes and decide to be different, but by doing that they lose the ability for their tv to be controlled by universal remotes. Not a great way to get and maintain customers.

The same goes for APIs.

There is an established set of http status codes that define how an API should respond in different scenarios. There’s nothing that says an API must use these status codes, but if software developers want integrators to have a low barrier to entry, they should use them.

Just as an example, with http status codes

• If you create something new, the API should return a 201 status code
• If you update something, the API should return a 204 status code
• If you load something, the API should return a 200 status code

Again, an API will work if don’t adhere to the standards, but it is much easier to pick up and learn if you do.

Getting Access To The System

You might discover the first time you use a new universal remote it doesn’t automatically control your tv. You have to hit that little program button and walk through an exercise that makes you hit the power button a bunch of times until the tv turns off.

The remote is going through a set of different codes to figure out which one communicates with this brand of tv. Once it figures out which set of codes works with the tv, you are forever good to go to control it.

APIs work just like this.

Most APIs have a level of authentication that integrators must use to verify they are who they say they are. Since an API provides access to the system, software companies want to make sure to weed out any malicious users as best they can. Nobody wants a bad actor to have the potential to intentionally mess something up.

Enter authentication. APIs have a multitude of different ways to verify users ranging from API keys to OAuth to basic authentication. No matter what type of authentication an API uses, the intent is the same: keep out the bad guys and uniquely identify the good guys.

Different Kinds, Different Uses

We’ve all been to that one friend’s place who has 7 different remotes on the coffee table that do 7 different things. This one controls the tv, while this one adjusts the soundbar, and this one is for the AC unit. They are all remotes, but they really don’t have the same function.

Believe it or not, there are different types of APIs that are used for very different things as well.

• A REST API is an API that gives you easy, intuitive access to different resources inside of an application.
• A GraphQL API is an API that is a little less structured that lets the caller ask for what they want specifically
• A WebSocket API is an API that acts like a push notification. The server makes calls to the client!

Just like our friend with the many different remotes, a complete software solution is composed of different types of APIs to provide a high value user experience.

Maintaining Customer Happiness

Customer retention is key to success in any business. You build up customer loyalty, you build recurring revenue, you continue to see growth as a result.

With our tv remote, happy customers will continue to use the remote, maybe buy another one for their other tv, and perhaps even recommend it to their friends and family. So how do you keep them happy?

Making sure your remote works on the first button press 99.9% of the time is a good start. It’s also important to guarantee every time you press the channel up button it changes the channel up and doesn’t do something like lower the volume or change the input.

With APIs, reliability and speed are your keys to success. Software companies put a heavy focus on making sure API performance remains high. Just like you wouldn’t use a remote that works erratically, customers won’t use an API that is not reliable.

Keep this in mind the next time you’re building an API, people look at performance just as much as they do functionality. It’s always worth a little power tuning to keep things reliable.

Conclusion

APIs are the foundation of modern software. They allow consumers to interact with a system to provide exactly the right experience they are looking for.

Through the use of established standards like Open API Specification (OAS) and http status codes, software companies can converge on a format that allows developers to just start working. No more long ramp up times learning the nuance of how an API was developed.

Everybody these days should know at least a little bit about APIs. From Alexa getting you today’s weather to your phone catering articles to you, the world runs on APIs. It’s the focus of software companies today.

I am a strong believer in the power of the metaphor and how it helps drive comprehension. Explaining APIs like you would explain how a tv remote works will help your friends, coworkers, and even mom understand them.

Next time you get a chance, be sure to spread the word and help make those around you just a little more technical.