How Does An API Call Work?
Application Programming Interfaces (APIs) are one of the most common pieces of middleware that you’ll encounter in software. They expose data from external programs so that you as a user can request, wait, and then (all going well) receive your much needed data. You may have used them a lot but not really understand some technicalities of the API call. If you’re interested in that, here’s my thoughts at a surface level.
Making a call to an API works in these stages:
- make the call to the API via its Uniform Resource Identifier (URI), giving a request verb, headers, and optionally, a request body,
- given a valid request, the API makes a call to some external program for data,
- the API gets a response from the external program,
- the API gives the data to the initial requesting program.
The following image accompanies that explanation.
I hope you’ve wrapped your head around this, but don’t worry too much. I’ll go over the 4 points of API communication in a little detail below.
Make the call to the API via its Uniform Resource Identifier (URI), giving a request verb, headers, and optionally, a request body.
The first thing you should note about the image above, is the vertical lines that separate the Requesting Program, API, and External Program. In this first example we’re going to focus on the initial relationship between the Requesting Program and the API.
First, what is a Uniform Resource Identifier (URI). You have a place where you live right? That’s an address, in a post code, in a city, in a country, on this earth. Not only is it unique to you, but additionally someone who knows your address will know where you live and be able to knock on your door. You can think of a URI as the same thing, but it’s the digital address of the application. As the requesting program, its your job to know what this URI is, and when you do, congratulations; you can knock on the door of the API program.
To continue with analogy of your address, calling an API would be equivalent to going to someones house and asking them to do something for you. Now that we know how to access the program, we need to know how to form our request.
Requests have a type to which they adhere. It’s called a VERB and the most common examples are: GET, POST, PUT, PATCH, and DELETE. This piece of information tells the API what sort of request you, as the requesting program,would like.
GET — I am requesting some information from you,
POST — I am requesting that you create this new piece of information,
PUT — I am requesting that you update a piece of information that you have,
PATCH — I am requesting that you update part of a piece of your information,
DELETE — I am requesting that you delete a piece of information that you have.
So you’re at the house and you want to ask for something. But which language are you going to ask in, and which format will the thing you’re requesting be given to you. Imagine you ask in French, but the person speak Mandarin. They won’t understand and won’t be able to help you. Now imagine that instead you ask in French, they understand french, you ask for a knife and they bring you a picture of the knife. This is a lot of hassle, and speaks volumes about the importance of the request and response format. In an API, we can ask for a specific format with Headers. Headers are meta-data for the API; they tell it about your data request and about what you want as a data response. We’ll use two common headers as an example: Content-Type and Accept.
Content-Type is a commonly used header that provides information to the API about what type of information is in the request body. We have this header because there are many ways to format the same piece of data and it’s important that we tell the API which format we put that data into. For instance, lets say that we had formatted the data in XML (a mark up language) as opposed to JSON (basically the default format as of writing this). Without this information an API might have been given completely valid data in the request but fail to do anything with it because it doesn’t know what it is and has no way of decoding it.
Accept is kind of the opposite to Content-Type. We ask in what format we would like our data response from the API. Let’s consider that we don’t specify a value for Accept. Well, shit; then we’re at the whims of the API as to what data it returns to us. Is it JSON? XML? A word document? We shouldn’t be guessing, we should certain. However problems can arise even when we do specify what we want as a data response. The API might not have the ability to return data in the format we want. That sucks, but ok; it is what it is. Even knowing this, we should always specify what we want in the Accept header because then valid requests and responses give us precisely what we’ve asked for. We can go to the door of the house, ask in french for a kitchen butter, and walk away with a kitchen butter knife.
Given a valid request, the API makes a call to some external program for data
A quick side note. Most APIs don’t actually store information themselves. They instead provide the connection piece to a third, external program. From the image at the start of this post, that external program is in the right panel. The role of the API is to listen, check for a valid request, and given validity, yield a response. But any data in the response comes from the external program; the API only handled it and presented it to us.
Let’s continue again with the example of going to someone’s house. We’ve already established that knocking on the door is like knowing the URI of an API. You could say that person who answers the door is the functionality of the API. So, you knock on the door and you ask for a common kitchen butter knife. The person who answered the door thinks everything’s ok (checking your validity) and goes to get the knife. Now, here’s where we add a new role to the example. I would make the argument that the kitchen is the external program, which the API is requesting data from. In this case, the request for data is to open the kitchen draw and take a butter knife.
The API gets a response from the external program
When the person who answered the door opens the draw, it’s analogous to an API requesting something from the external program. This is really where the example falls flat though. A person would rummage through a draw, find the common butter knife, take it from the draw, and then give it to the person who knocked. Why is this wrong? Well, the external program has one fewer knife and the API spent time looking for it.
In an actual relationship between an API and external program, the API would execute a query or a function on the external program to yield a copy of the data. This query or function would be work done by the external program. To make our house analogy equal, this would be the equivalent of the kitchen draw when asked for butter knife just spitting the thing out. That isn’t the only difference between the house analogy and the API. We’re also not returning a copy of the data if we were to take a knife from the draw. So not only would the draw have spat the knife out, it would also have 3d printed it.
In summary, the API makes a request of the external program. The external program does some of its own work and passes a copy of the data to the API. Now the API has the data, how does it pass it back to the requesting program?
The API gives the data to the initial requesting program
With the butter knife in hand, the person in the house approaches the door; giving the knife to the person who knocked and asked for it. This process is quite simple, but, for an API to do this with a requesting program, there can be a few extra steps.
It’s very possible that the API could just return the raw data, but sometimes the format matters (as we seen earlier in this post). If the format of the data isn’t usable by the requesting program then its useless. Therefore the API will consider what information was in the Headers of the request. Remember that set of meta-data (information about the data), well we’re getting back to it. We used the example of the Accept header to represent in what format the requesting program wants the data. If a format change was required (given that the API can change to this specific format) this is where the API would make that conversion.
For one last time, lets go back to the house example. We’ll use the magical kitchen draw for continuity. The resident of the house asks the draw for a knife, and the kitchen draw obliges; magically spitting out a machete. This is not a butter knife, but it is always returned whenever you request a knife in the external program. Now it’s the job of the resident to change that machete into a butter knife. *Bang*, *Clang*, *Smack*. However the resident goes about it, they’ve converted the machete into a butter knife to give to the person at the door (who is none the wiser of this process).
This is exactly what an API might have to do. For instance, if the requesting program wanted the data formatted into JSON but the external program spat out data in XML; it is the job of the API to convert the XML into JSON.
So yeah, that’s how I see the steps of a call made to an API. You make a request with some metadata to the URI and ensure that request is valid. The API receives that and makes its own request of an external program. The program spits out the data that the API requested. A conversion may or may not happen, but the API then yields the external programs data as the response that you initially requested for. It’s simple, and it’s awesome.
