Gather ‘round children. It’s time for our very first Explain Like I’m 5 post, this time discussing Application Programming Interfaces, or API’s. We’re going to focus on web API’s which are the most common and probably the one’s you (knowingly or not) interact with on a daily basis.
Before we begin, this post is directed at someone with little to no technical knowledge of programming. For this reason, I’ll try not to use super technical terms. However, I’ll put the technically correct term in parenthesis just for clarity.
First, clear your mind of any confusion you have around API’s, we’re going to start fresh.
I want you to think of an API as a web application (technically its an interface not an application) like Facebook, except it has no user interface for you to click on or interact with. Instead of you interacting with the API directly, web applications interact with it on your behalf.
So now you’re asking yourself — “But why would a web application need to interact with an API?” Very astute!
An API is used as “the middle man/woman” between the web application and (usually) a database. This is an essential point. You wouldn’t want someone to go in and say, accidentally delete everything in your database. So instead, the companies provide an API with tons of restrictions so that any web application can interact with it to get the data necessary.
So in essence, an API is an interface created by companies to allow external parties access to their data, without giving them total freedom to look at, or edit anything they want. The external parties can only look at whatever the API permits. It’s important to remember that we are talking about Web API’s, which are more common than other types, but the same logic applies to all.
That’s as ELI5 as I can get it. Want to know more? Keep reading.
To paint a full picture, let’s go through a typical (hypothetical) flow from a users point of view.
- You visit Flixable.com which allows you to search movies and shows currently on Netflix.
- You search for a movie.
- Flixable (referred to as the client), makes a request to Netflix’s API with the name of the movie you want.
- Netflix’s API checks Flixables credentials (provided as part of the request) to see if it has permission to even make a request.
- Once the credentials have been verified, Netflix’s API will query their database, and based on what it found, it will return the appropriate response.
- The response is handed back to the client.
- The client displays what was returned from the API, which is either nothing found, the data on the movie you searched for, or sometimes an error message.
In this case, the web application Flixable.com is called the client. The data it asks for from the API on your behalf is called the request. The data that comes back from the API is called the response.
What kind of requests can we make to the API? To answer this, first we need to understand how the web app/client actually communicates with the API. Web API’s communicate through HTTP (yep, the same protocol used to get web pages).
Within the HTTP protocol, there are a few commonly used actions we can take (typically called HTTP Verbs). These actions/verbs include, but are not limited to:
- POST
- GET
- PUT
- PATCH
- DELETE
Each verb is for a specific purpose. If you want to read something from a database, you make a GET request to the API, and then the API will fetch the data for you and give it back as a response.
If you POST to an API, this will create something, like adding a new movie to a database.
PUT is for update/replace, PATCH is for update/modify, and DELETE is for create. JK, it’s to delete something. Wake up!
Okay, so we can make all types of requests, but how does the client actually send those requests to the API? You know how you’d type in a URL into your browser to go to a website (in the background the browser makes a GET request for the HTML page from some server)? Communicating with an API is very similar.
Let’s say you type “Walk Hard” into the search box at Flixable.com and hit search. Flixable (the client/web application) grabs your search word, does a GET (remember, we’re getting data) to the URL of the Netflix API (api.fake-netflix-api-url.com/movies), and will usually append your search word to that URL as a URL parameter (i.e. api.fake-netflix-api-url.com/movies?walk%20hard).
We’re going to over simplify it but essentially what happens is the API will receive your request, check that you’re authorized to use the API, then it will use the path (/movies) and the URL parameter (walk%20hard) to perform some kind of task and grab the data from the database. It then spits it right back to the client/web application as a response object with all the data it found (or nothing if it didn’t find anything).
Now with this core knowledge, lets go through our entire scenario again but with more detail.
- You visit Flixable.com which allows you to search movies and shows available on Netflix
- You type “Goodfellas” into the search box and hit search.
- Flixable (the web application) will grab your search term from the search box, and on your behalf make a request to the Netflix API. The request is all the information required by the API, like credentials it may need to make the request and any other necessary pieces of data. The request is made to the URL provided by the Netflix API, in this case api.fake-netflix-api-url.com/movies. The application will usually append your term to the API URL endpoint as a parameter (i.e api.fake-netflix-api-url.com/movies?goodfellas).
- Netflix’s API checks the Flixables credentials in the request. It sees that Flixable is indeed allowed to use the API, and so it uses the URL and the URL Parameter to search the Netflix Database for that movie. Once it’s found something, it will send all the data back as a “response”. If it doesn’t find something, it will usually send an error or an empty response. If something goes wrong, it will send an error back as the response.
- The response is handed back to the client. The client does whatever it needs to do to display the returned data to the user.
- The user views the data.
We’ve glossed over a lot of the details, but this core knowledge is enough for someone to be able to talk to a developer about what an API is, and why its important in a development scenario.
Thanks for reading my first ELI5 post! Hopefully it will help you in one-way or another :)
