What is a REST API?

What is a REST API? That question can be broken down into 3 seperate questions:

1. What is an API , in general?
2. What is a web API, and how do we use it? What is it for?\
3. What is a REST API? How are RESTfull APIs organized?

Today, we're going to step into the shoes of a full-stack developper who has to set up a website for a bookstore. And as our imaginary developper wants to do his job well, he's going to set up an API. What is an API? And why does our developper want to create one?

General concept: what is an API?

An API stands for "Application Programming Interface". There are two parts to that: Application Programming, on the one hand, and Interface on the other. First of all, what is an "interface"?

Well, it's quite simple. The name says it all. The word "Interface" is inter / face. It's something that is in between (inter) two things that are facing each other. For example, the surface of the sea is the interface between water and air.

Often when we talk about an interface, we mean the thing on the screen that explains what the software is doing and allows the user to interact with it. In this case, the interface is the thing that connects the user and the software. That's why we talk about User Interface or UI, which is the "surface" between the human and the software.

In the case of the API, the two entities that interact are pieces of code. We speak of a software library's API when referring to the list of public functions it provides. This includes their signature, that is to say: the type of parameters these functions accept and what they return.

But most often, today, when we talk about APIs, we mean communication via the Internet, via the Web. The web communication we are most familiar with occurs when a browser requests a web page, to which the server sends back a lot of HTML and CSS.

Here, in the case of an API, a piece of code (Javascript, for example) sends a request to the server. And the server answers in a format that a computer can understand. Nowadays we often prefer JSON returns since they are also readable by us limited humans.

But at first, computers would respond in XML. That XML was the "X" of a technology that was once the rage but has now faded away into the woodwork: AJAX. But it's worth looking at why this technology was so fashionable. And behind that lies the question: what is the point of web APIs?

What are Web APIs for?

Web APIs are what makes Angular and Vue and React and everything called Web 2.0 work. In Web 1.0 the user requests a page, and the server sends it back, and it is refreshed.

In Web 2.0, and in frontend frameworks in general, we no longer need to refresh the page to access new information, a new state of our site. Because the code downloaded to our browser calls the server by itself and updates the display without needing to change pages.

For example, if you click the "follow" button, to the right of this article, it doesn't reload the page. It updates the state of the button without reloading the page. Try it out and see for yourself!

As you can see, calling a web API allows for dynamic content, without the painful experience of waiting for a page to load. Let's take a simple example. Let's say you're wondering which city to spend your weekend in. You enter a city name in a search bar. You start typing L.

The search bar updates with a drop-down list. It contains the city names and the current weather: London, rainy, 20°. Liverpool, sunny, 10°, Lyons, Leeds… etc.

In short, the code downloaded to your browser can guide you directly. And all this because that code sent a web message to the server. It said: "hey, give me the name of the cities that start with L, with their current weather". And the server responded with a JSON document that provides all the information you need.

So that's what web APIs are about.

It's worth mentioning here there are different web API formats. There is one default reference format, one king of the pack, so to speak. The format is used in a lot of tutorials and many public APIs. It helps that it is easy to explain and understand. That format is REST (which stands for REpresentational State Transfer).

There's another more fashionable web API format created by Facebook called GraphQL. GraphQL has a radically different philosophy in how it operates, but that deserves a separate article. For now, though, let's take a look at the structure of REST APIs, and how they are built.

What is a REST API?

To start with, you should know that HTTP actions (or verbs) have associated meanings. When you open a web page, your browser actually makes a "GET" request. When you submit a form, your browser usually sends a "POST" request, or in some cases a "PUT" request. And when you ask for something to be deleted, your browser might be sending a DELETE request.

What are those meanings? Well, a HTTP GET request means a read request. A POST request is a resource creation request. A PUT request is a resource modification request. And a DELETE request is a …resource deletion request. We've been talking about resources, but what is a resource?

If you know how a relationnal database works, a resource is very similar to a row in a table, i.e. an item in my database. Let's rewind back to our bookstore website. I have books and authors in my database. Both of these are resource collections. And so I'm going to associate an entry point (i.e. a URL) with each of these resources. Let's say my API is at "/api" (e.g. on localhost:8000/api or at yourserver.com/api). So the entry point for books will be "/api/books/". For authors it will be "/api/authors/" And so I will interact with these entry points, depending on what I want to do.

Let's start by reading data. So we'll be making GET requests. For example, let's say I want to retrieve all the authors I have in my database. In this case, I'll make a GET request to the authors endpoint, "/api/authors". This is the simplest request, it retrieves the whole collection.

Now, let's imagine that I know the author I'm interested in (say… Douglas Adams) has id 42 in the database. To retrieve his information, I send a GET requests to "/api/authors/42". This path, with the id added on, identifies the author resource I am interested in.

We can even imagine wanting to retrieve specific information about an author, such as his name. In this case, we could send a GET request to "/api/authors/42/lastname" that would retrieve the name (So here, Adams).

If we want to take things even further, we could imagine wanting to retrieve the collection of books written by our author. In this case, we would send a GET request to "/api/authors/42/books".

A quick word on the differences between REST and GraphQL

Now, two small details here, in passing, to compare REST with graphQL.

The first is that accessing the "books" field of "/api/authors/id" is one way of following the REST standard. But the API creator may well have made different architectural choices. And that's true for other APIs in the wild too. APIs can be more or less RESTful. It's not just black or white.

And therefore the only way to know what is implemented is to read the documentation — if there is one !— or the code. GraphQL's advantage here is that it is self-documenting by nature: you can send a query to the graphQL API that returns the documentation. (It's what is called "introspection"). And that allows for quite a lot, such as playgrounds with autocomplete.

The other difference is that using REST you can either retrieve all the fields or just one. There is no in-between, if you just want to specify 3 fields out of 50 that you want to retrieve, you can't. And that's GraphQL's other advantage: it allows you to define the shape of the data you want to retrieve. 
 
But let's get back to our REST API.

More advanced queries

Let's imagine that we want to create a new book. All we have to do is send a POST request, with all the fields filled in, to the "/api/books" entry point. If we wanted to create an author, we would send the relevant request data to "/api/authors".

Now if we want to update our author, we send a PUT request to the path that "belongs" to the author (i.e. with the id on the end), with the new data. And if that has been implemented, we could imagine sending a PUT request to a single field of the resource. For example: "/api/authors/42/date_of_birth"

And of course, if we want to delete data we send a DELETE request on the entry point that corresponds to what we want to delete.

In conclusion

There would be a lot more to cover such as "idempotency" and authentification and authorisation, and HTTP response codes, but that would be a way longer article. In the meantime, I hope this article has been useful to you. If you need help, if you have any questions, please let me know in the comments.