What the heck is an API? A Beginner's guide to APIs

What is an API?

API is short for Application Programming Interface.

It's how one computer (or software) can talk to another computer (or software).

Basically, an API is where a computer or software application (the client) asks another computer or software application (the server) for some data or to do some task.

In the case of humans, imagine I wanted to talk to you but you were in New York while I was in London. I can't just walk over to you and talk to you face-to-face. But, I can pick up my mobile phone and dial your number. That will cause your phone to ring. You pick up your phone, and we can talk through the use of our mobile phones. It's similar with computers; they can't talk to each other directly. They need an API to enable that communication.

Another way to imagine it is by thinking about making an order at a restaurant. You, the customer, cannot talk directly to the chef and tell her what you want. Instead, you need to go through the waiter. The waiter takes your order and relays that to the chef. The chef then prepares what you want, gives it to the waiter, and the waiter gives it to you. In this example, you are the client computer, the chef is the server and the waiter is the API through which you and the chef communicate.

An example of an API: SWAPI

The Star Wars API (https://swapi.dev/) is an API that provides data about Star Wars. If you ask it for planets/3/ it will give you all the data about planet 3.

OK, so now you sort of know what an API is. But what is a RESTful API?

REST stands for REpresentational State Transfer.

You might be asking yourself, "What in the world does that mean?" This article on Medium explains it really well:

It means when a RESTful API is called, the server will transfer to the client a representation of the state of the requested resource.

For example, when a developer calls Instagram API to fetch a specific user (the resource), the API will return the state of that user, including their name, the number of posts that user posted on Instagram so far, how many followers they have, and more.

The representation of the state can be in a JSON format, and probably for most APIs, this is indeed the case. It can also be in XML or HTML format.

Usually, a RESTful API will return a JSON data structure. JSON stands for Java Script Object Notation and consists of key-value pairs.

HTTP Requests and Responses

HTTP is a communication protocol that computers (or applications) use to communicate with each other. It controls how computers communicate with each other.

The client computer will send a HTTP request for what it wants to the server and the server will return a HTTP response. Note that a RESTful API usually uses HTTP, but it does not have to.

There are four methods used by HTTP requests. These are known as the CRUD methods: Create, Read, Update, and Delete.

GET Requests

Let's take an example: www.facebook.com

When we want to go to Facebook, we are telling our browser to get us data from www.facebook.com and then show it to us. We just want to load the website; we don't want to change or delete anything, we just want to see it. This is the most common type of request.

POST Requests

A POST request is where we request to make a brand new resource. Ideally, when we make a POST request, it will return all the unique identifiers for that new resource to us so that we can then make a GET request using those unique identifiers.

For example, say we want to create a new user on Facebook. We go to the sign up page and put in all our details to create the new user account. We then click 'submit', which sends the request to the server. The server receives it and recognises that it's a POST request (to make a new user; a new resource). It then makes the new user for us and sends us the login information for the new user. We can then use that login information to make a GET request to login to Facebook and see the contents of the page.

Going back to the restaurant metaphor, this is like ordering a pizza: you tell the waiter that you want a Hawaiian pizza. The waiter then tells the chef that you want a Hawaiian pizza. The chef prepares the pizza for you, which the waiter then delivers to you. This is a POST request because you have asked the chef to prepare a brand new resource: a Hawaiian pizza.

DELETE Requests

A DELETE request is where one computer asks another computer to delete a resource. For example, if we want to delete some photos from Facebook, or we want to delete a post from Instagram. When using DELETE, we need to be cautious that we don't delete entire lists by mistake! To avoid this, give the DELETE method a specific endpoint.

PATCH Requests

A PATCH request is when we send a request to update a part of the resource.

For example, taking our restaurant example, imagine that you've finished your meal and the waiter brings you the bill.

While going through the bill to check it, you notice that you were charged the wrong amount for your Hawaiian pizza. You were charged $20 instead of $15. You did have pizza (and that is correctly recorded in the bill), but the amount charged is incorrect. You want that updated.

You notify the waiter of the error and ask for the bill to be corrected. The waiter then tells the chef or whoever is in charge of the bill, the bill is then corrected and the new (corrected) bill is given to you.

Another example would be when you ask a credit agency for your credit file and you want to check whether the details they have are correct. You make the request (GET request), the agency emails you the credit file and then you check it. You notice that they've got your title/prefix wrong: they've recorded you as Mr Sally Potter instead of Ms Sally Potter. You then send the agency an email asking them to correct this small error. This is a PATCH request - the file that the agency sent you was indeed the correct file (your credit file) and it contained all your details, but one of the pieces of information was wrong and you've asked for that to be corrected.

Although we can use PATCH requests to update information, not all browsers and frameworks accept PATCH requests. This is where PUT requests come in (see below).

PUT Requests

A PUT request is when you ask for an entire resource to be updated (not just a part of it).

Going back to the restaurant example, this would be where you look at the bill and notice that you got charged for a beer which you didn't order or drink. What you actually ordered was a bottle of sparkling water. You therefore ask the waiter to please remove the charge for the beer from your bill and add in the sparkling water.

Summary Table for HTTP Requests

Responses

When you make a request, the information is conveyed to the server and the server provides a response. The response will be an HTTP status code.

There are different HTTP response status codes, ranging from 100's to 500's. Usually, a response in the 200's indicates that things are good, and a response in the 400's means something on your end is not quite right. For a full list of the different HTTP response status codes visit the MDN docs page on HTTP response status codes.

Further reading

If you're curious and want to read more about Restful APIs and HTTP, here is a good article about REST & HTTP. This article explains the difference between a REST API and a HTTP API.

Photo by Marvin Meyer on Unsplash