What is a REST API?

As a software engineer that works regularly on back-end systems, a REST API is one of the most important things that I work with on a daily basis. In this post I’m going to explain in detail, and in my own style what a REST API is, its significance in web applications and business operations, as well as how to build one super easily with JavaScript.

Note: The acronym REST API = REpresentational State Transfer Application Programmable Interface

Interfaces

First, I want to get into what an interface is. I will provide 2 real life analogies here so you have reference points to think with.

Example 1: Traffic Lights

A traffic light is like a contract between all people that use the roads:

• If your side has a red light, everyone on your side must stop
• Similarly, if your side shows a green light, everyone on your side must move and go

You can think of this “system” and the “definition” of traffic lights (whatever we understand it as) as an interface for communication between humans that use roads, whether to drive on them, ride a bicycle or walk as a pedestrian.

What I want you to imagine is something like this:

Following this graphic, a traffic light is an interface that all parties (drivers on the road) are using to access information about whether to stop at a junction or keep moving. The traffic light distributes this information to anyone who wants to “access” it (or look at it). In this case, the parties are not sending any information “to” the traffic light; they are just receiving.

Example 2: Human language

If you speak Spanish with your family, say with your brother, then the rules and grammar of the language as well as the words all make up the definition of the interface that you both use to communicate between you. In addition, facial expressions – like raised eyebrows – or using hands are also a part of a commonly understood human communication interface.

There are many more fascinating examples that we can find in our world. The United Nations is an interface for communication between nation states of the world, and the Premier League table is an interface that we use to know which football teams are the very best in England.

You’ll notice that interfaces can be very open ended and can define rules at any level. The networking protocols that make up the internet are extremely powerful interfaces because we all use them in our daily lives. On the other hand, a schedule sheet that keeps track of shifts at a local coffee shop is an interface that is only relevant to the folks that work at that coffee shop.

APIs

An API is basically an interface for computer programs. Your phone knows how to display this article to you in a form that you can read because of many different interfaces (IP – Internet Protocol, HTML, CSS, JavaScript and many more). Some of these interfaces define a language like JavaScript, and others define what structure information should be sent in between computers so they all know how to read it and what it means.

A REST API defines custom rules for how applications talk to each other on the web. This is what makes REST APIs so powerful.

Managing business with customers using REST APIs

Let’s say that you own a pet supplies store and you want to delight your customers and clients by letting them sign up on a web app and register for monthly subscriptions for supplies at a discounted price – supplies like dog food or pet cleaning supplies.

Your app would store this information in a database like PostgreSQL or MySQL, and you would define a custom set of rules (i.e. an interface) for letting customers access this information.

• Your customers would likely want to send over their payment method information, like credit card details
• They’d want to see what products are available to buy, and whether or not they can be bought once or continuously via a monthly subscription
• In addition, you’d want to be able to add and remove products, define their prices, and maybe manage access for users

In a proper real-life business example, you’d actually be setting up numerous different APIs (interfaces) for managing this.

• You’d have an API for managing users – doing operations like creating a user, editing a user, deleting a user
• You’d have an API for managing products
• An API for managing subscriptions

and so on…

You as the owner of the store would have more capabilities to do more with information than your customers, but each party would have ways to send and receive information using the interface or API.

Example walkthrough

If you wanted to see how many of your customers are subscribed to receive dog food packages via delivery on a monthly basis, this is how it would work:

1. Your front-end application (on your phone or desktop computer) would send a piece of information like /subscriptions?type=monthly&category=dogfood to your back-end application. Both of these applications would have knowledge about the structure and definition of your API(s)
2. Your back-end application (running on a server somewhere) would receive this piece of information and break it down, following the rules and definitions of your API (interface) defined in the code of your application – this could be in any language, like JavaScript, C#, Ruby or Python
3. Your web app would check whether you are who you say you are (authentication) and whether you (the person requesting for this information) actually have the rights to access this information (authorization)
4. Next, your web app will retrieve the information from your storage (database) and send it back in a form that is strictly defined by your API
5. Lastly, when you see this information on your phone or your desktop computer, your browser will know how to display it to you because your web app defines the structure of this information on both the back-end side as well as the front-end side

Building a simple REST API with JavaScript and express.js

Express.js is a library in the JavaScript ecosystem that empowers programmers like you and I to easily spin up REST APIs. Let’s build one right now.

Step 1

You want to make sure that you have Node.js and NPM installed on your system (just google how to do it if you don’t know – it’s very easy). Next, create a new folder/directory anywhere and open a terminal/command prompt window inside it.

Step 2

Then, Initialize your project using the command npm init -y and install express.js using npm install express.

Step 3

Create a new file called index.js in your folder/directory and paste the following code below (and obviously, save it):

const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => res.send('Did you work out today?'));

app.listen(port, () => console.log(`Server running on port ${port}`));

This code defines a very simple version of a back-end application which has only one API named /. If we send a GET request for information to this API, we will get the information Did you workout today? back.

GET is a type of information request that we can define in a REST API when we are creating it. There are many other clear and well defined types of information requests in the REST ecosystem including, you can learn more about this here:

• POST – With this type of request, we can include chunks of information in the request body as an object, which we then send to the back-end server every time we trigger this request
• PUT – Tells the back-end server that we want to update something, like updating the price of a product or changing the email of a user
• DELETE – This type of request indicates to the back-end server that we want to delete something

Step 4

Back in your terminal/command prompt, start your back-end server application by running the command node index.js.

Step 5

Open a new terminal window and execute the command curl http://localhost:3000/. This simulates sending a request to your back-end API. The / at the end tells the application what information we want to request.

PS: curl is a simple terminal/command line tool for sending HTTP requests to any server, whether on your computer or anywhere on the internet, and localhost is an address alias that represents your own computer. You should try executing curl https://www.google.com to see that we can also get webpages from the internet using this tool.

Your terminal should output this text:

Did you work out today?

We have just defined a very simple API.

Now, let’s extend this and implement a very simple version of the pet store products API where a customer can ask us “what products do you have?” and we respond with a list of products.

Step 6

Add the following lines of code to your index.js:

const express = require('express');
const app = express();
const port = 3000;

app.get("https://dev.to/", (req, res) => res.send('Did you work out today?'));

+ const products = [
+  { id: 1, name: 'Dog Food', price: 10.99 },
+  { id: 2, name: 'Boat Plush Toy', price: 15.99 },
+  { id: 3, name: 'Cat Scratching Post', price: 19.99 }
+ ];

+ app.get('/products', (req, res) => {
+  res.json(products);
+ });

app.listen(port, () => console.log(`Server running on port ${port}`));

Here, we are adding a list (array) of products and we add a new definition for an API route called /products which returns the list of products. Thus, our users can call the API and request for this information like this:

curl http://localhost:3000/products

Voila!

This is how easy it is to create simple REST APIs using JavaScript, and I would highly recommend this process for testing your personal projects.

It should be noted that actual business applications and complex back-end systems have a lot more detail, configuration and definitions than this. If you’d like to read more about more complex systems and enterprise level programming that supports high-level business, let me know in the comments and follow me to get updates for future posts.

If you have any questions or want to ask me more about anything related, let me know as well in the comments below.

You can also follow me on X @mbzdotdev.

Cheers.