How do APIs work?
Welcome back! Since my previous article, I hope you’ve noticed some API integrations in your everyday tech usage. Last time we met, we went over some high-level details about APIs:
- APIs allow for the externalization of a feature or some functionality
- APIs are programmatic interfaces that allow two (or more) applications, services, and/or devices to work together
- Code needs to be written to allow the two things to talk to one another
So we have a sense of why APIs exist and what they make possible. Let’s go a little deeper. How do APIs work? How are they designed? How are they controlled? Where am I and how did I get here? These and all your deepest API longings shall be revealed!
The Design of APIs
Have you ever assembled furniture and been awed at the precision of the interlocking parts? Or maybe you’ve had the opposite experience, like assembling a lighting fixture from a big box hardware store. I’m getting PTSD as I write this...
I recently put together a new fire pit for my backyard and (of course) I didn’t look at the instructions. There were only four large pieces of metal and three (only three!) screws to put the whole thing together. Being the overconfident doofus I am, I started assembling it thinking, “How hard could this be?” Five minutes later, my frustration was mounting. “What kind of idiot designed this thing? How could they sell such a shoddy product?”
Then I read the instructions and realized I was missing a simple step that made the whole thing come together so easily. I could have saved myself a lot of frustration and some time if I’d just read the instructions. But no…
And it turns out that the assembly instructions were quite ingenious. I never would have guessed that the threaded nuts on the three included screws would have been used to stabilize the whole assembly process.
APIs are kinda like that. A good API designer makes it as clear and simple as possible to do complex work, like integrating the functionality of two software products. Oftentimes, you have to read the instructions even if you think you know what you’re doing.
Using API Endpoints
For example, let’s say you and I wrote some basic Calculator software. We send “3+3” and it sends “6” in response. We send “10-6” and it sends “4” in response. Pretty straightforward, right?
Well, when it comes to sending messages on the computer, we have to be very, very specific about the message itself. We have to make sure the Calculator software receives the exact kind of message it is expecting and we have to know exactly what kind of response we’re going to get. “3+3” is not the same as “3 + 3” because there are spaces in the second message. And then there’s the context of the message.
Let’s imagine I wrote “3+3” on a sheet of paper. Could you read it? In your head you might imagine I’m using a black pen on a white sheet of printer paper. But what if it’s a black sheet of paper and I’m using a black Sharpie to write on it? What if the size of the paper is no bigger than a grain of rice? This might sound silly to you, but computers can’t make assumptions.
When sending a message to a computer, one has to be very specific about the type of message and the way the message is presented. All of these details need to be considered when using an API. So, an API designer needs to be very specific about instructing others on how to use their API.
For our basic Calculator service, we might have a service that’s called “Addition” and another that’s called “Subtraction.” The Addition service might expect two numbers or maybe it can handle any number of numbers. We could send “3,5,4,1,2” (assuming Addition is expecting commas between numbers) and the Addition service interprets that as “3+5+4+1+2” and sends “15” as its response.
These Addition and Subtraction services are “endpoints” and the messages sent back and forth are called “payloads.” Remember these terms because we’ll use them again later.
Securing an API with API Keys
Let’s say our Calculator service is getting seriously popular. A LOT of people are looking for basic Addition and Subtraction services and our hosting and bandwidth costs have gone out of control. Our Calculator service is a huge success, but we now want people to pay before they can use it. Fantastic, right? Well, how do we control who has access to our service?
We use API keys.
API keys are like keys in the real world. Your front door has a lock on it that only opens with one key. There may be many copies of that one key (your mother has one, your neighbor has one, your brother has one, etc.), so multiple people have access to your home. APIs aren’t that different.
What’s nice about software is we can create new locks out of thin air and we can create uniquely complex keys that fit those locks. Whereas most locks have keys that are about two inches long, the keys used to secure APIs are as if they’re a mile long. They’re extremely complex!
An API key can look something like this: bd6f075a5409b85d4ac2f327aad1b182. Or an API can be literally 8-10 times longer than that. Pretty cool, right?
Even better, every API key can be assigned an owner. So, that bd6f07 key above can be the specific key you give to a specific customer and can only be used by that customer.
Many APIs, even if they’re open to the public, require the use of a key.
What’s Next?
I thought we’d get to RESTful APIs in this article, but we didn’t. And this post is already longer than I’d hoped! So stay tuned for part 3. I don’t know how many parts there will be, but hopefully you find this series useful.
Do you need clear-headed technical content like this article?
Writing easy-to-understand technical content is difficult work. If you or your brand are looking to become a thought leader, you should consider hiring expert content creators like Edify Content to help you. We can generate ideas, create and manage a content calendar, get newsletters out to your followers--heck, we’ll even do it all for you! Just reach out to [email protected] to learn more.