Contrary to popular belief, APIs are a technical concept that anyone can understand without knowing any code.
API stands for Application Programming Interface, and is often referred to as a connector that helps one software communicate to another piece of software. To explain in detail, I’m going to compare and contrast an everyday email to an actual API request.
Firstly, to describe APIs, the main goal of an API request is to take incoming information and save it into a database (databases can be imagined as Excel files).
I will begin by describing APIs from a technical perspective, but these concepts will be tied together shortly, so don’t worry.
API requests consist of:
Headers: these commonly consist of an authentication method (eg: an API key).
A Request Method: this consists of either getting the information, posting new information, updating information, and deleting information.
Data: often referred to as the payload of the request. This consists of all of the information needed (if information is needed) inside of the request. This is saved in the form of Key/Value pairs.
To break this down into a more understandable process, imagine a town is hosting a race this weekend. There are two race times, Saturday at 10am or 11am. In order to sign up for the race, runners must first pay online to get a ticket with an order confirmation number. Next, they have to email the front desk with that confirmation number and the time they want to sign up for the race. Lastly, the manufacturing company making the race tickets needs an excel file consisting of all runners participating in the race. The excel files must include six different columns: the runners’ email address, their first name, their last name, sex, age, and the time they’re racing at (10 or 11am).
In this example, the front desk worker, named Karen, takes every email sent to her inbox, confirms the order confirmation number, and copies the email address, first name, last name, sex, age, and race time into the excel file.
An example of one of these emails is below:
What does Karen need to know in order to move this information to the excel file? The questions she may ask herself prior to copy and pasting each are:
Is the senders order confirmation number correct?
What’s the runner’s sex, age, and race time?
What is this person's email address, first name, and last name?
Once confirming the above three questions, Karen now opens the Excel file and adds the email, first name, last name, sex, age, and race time into the corresponding rows.
Next, I’m going to demonstrate how Karen’s job and this email can be completely replaced with a single API request.
Headers: In the example of Karen's emails, the first thing she does is check to see if the order confirmation number is correct. This is very similar to the behavior of how software receives API requests. The first thing a system does when receiving an API call, is to check and see if the API key is present and valid. This is frequently referred to as authentication.
A Request Method: The next thing needed for an API request is the request method. In all API use cases, the goal is to communicate with a database. There are four different ways you can do that: obtaining all information present, adding to the current information, editing the information, and deleting the information. These four ways of interacting with a database can be explained through Karen:
Karen’s current job is to add all new runners to an Excel file. The notion of adding a runner to a file is the exact same as the API request method called the POST request. Data from the API call (or email in this case) is directly added to a database (or Excel file in this case).
Now, imagine if someone sends an email saying they’d like to change their race time to 10am instead of 11am. Karen would go into the Excel file, and change the runner’s participation time. This is the functionality expected from the API request method, PUT, which serves to update information in a database
Similarly, if someone emails that they need to cancel, Karen would delete their column in Excel. This models the method DELETE, which simply deletes information in a database.
Lastly, Karen at the end of this is going to send all of the data to the manufacturer. This is similar to the most common API request method of all, a GET request, which returns information from the database. In this case, the manufacturer will want all the data within the database so they can make a GET request for all of the data. However, GET requests can also return more limited subsets of information.
Data (Payload): The last part needed in an API request is the body (or payload). Computers are very dumb (for now). They can’t read the above email and automatically assume the sender's first name is “Andrew”, the last name is “Smith”, and send that data to their appropriate columns in Excel intuitively like a human would. A computer also doesn’t need all of the pleasantries of human spoken language. Thus, we can cut out all but the specific information we needed for the Excel document. This stripped down language is essentially what “Data” is in the coding context.
In order to communicate our data between any computer, we need to speak a language that all computers understand. The two most common languages computers understand are JSON (Javascript Object Notation) and XML (Extensible Markup Language). Both of these are standardized formats for passing data from one computer to another so that every computer understands each other. This then turns the data into a form of Key and Value pairs. The Key refers to what the row in excel needs to be, eg: “First Name” and the Value refers to the entry in that key, eg: “Andrew”.
In code, this would look like: (in the format of Key/Value pairs where the left is the “Key” and the right is the “Value”){
“first_name”: “Andrew”,
“last_name”: “Smith”,
“email”: “andrew.smith@klaviyo.com”,
“sex”: “male”,
“age”: “25”,
“time”: “10am”
}
This is an example of actual data inside of an API request. If anyone wanted to edit this API request to either add a new row, or change the row name, they’d simply need to edit or add a key.
The main takeaways from this article are: in order to compose an API call you need to
Authenticate to the software being reached out to
Specify what type of request it is (GET/PUT/POST/DELETE)
Format data in either JSON or XML
The end goal of any API call is to either retrieve information, add information, update information, or delete information from another software.
Knowing how APIs work is the key to unlocking an understanding of all technology.