DEV Community: Bilal

What is a REST API?

Bilal — Sun, 10 Mar 2024 19:53:13 +0000

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:

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)
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
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)
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
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('/', (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.

Here's how you can upload tons of data to a PostgreSQL database in a snap

Bilal — Fri, 07 Jan 2022 12:18:24 +0000

Prerequisites

Python
A CSV file containing data

1. Install psycopg2

psycopg2 is the python library we are going to use. Run the following command in your terminal to install the package:

$ pip install psycopg2

2. Imports

Spin up a text editor and add these imports to your python file. We will use the csv package to import data from a csv file.

import psycopg2.sql as psql
import psycopg2.extras
import psycopg2
import csv

If you're curious, psycopg2.sql contains SQL related helpers for generating SQL queries using python, and psycopg2.extras contains the most important method of this tutorial - execute_values() - which we will use to finally execute the import query.

3. Create a database connection object and cursor

These objects can be treated as a singletons which will hold the connection to the database and they can be used multiple times.

DB = psycopg2.connect(
    dsn=None, 
    dbname='your_database', 
    user='postgres', 
    host='localhost', 
    password='password'
)
db_cursor = DB.cursor

4. Load the data from your csv file

Place your csv file in the same directory as your python script (or just update the file path to point to wherever it lives)
You can use the following code to easily import the csv data

with open('your_csv_file.csv') as f:
    reader = csv.reader(f, delimiter=',')
    allrows = []

    for line in reader:
        allrows.append({ "column1": line[0], "column2": line[1] })

line in the for loop is a list of all the values in the csv row currently being looped through. line[0] would be the first field, line[1] the second, and so on.
For each line/row in the csv that is looped over, we create a dictionary (map) where the keys are the field/column names and the values are... the values.
The allrows variable will store a list of all the created dictionaries (each representing a row which we will insert).

PS: It's important that the keys be the exact same as the column names into the table you want to insert your data into. This consistency is required to make the rest of the steps below work. You can surely choose to use different names, but then you'd need to also update the steps below to work with that.

5. Generate re-usable SQL

In this step, we will generate some SQL using the following function:

def create_sql(table_name, column_names):
    query = psql.SQL("INSERT INTO {} ({}) VALUES %s").format(
        psql.Identifier(table_name),
        psql.SQL(', ').join(map(psql.Identifier, column_names))
    )
    query2 = psql.SQL("({})").format(
        psql.SQL(', ').join(map(psql.Placeholder, column_names)),
    )

    return query.as_string(DB), query2.as_string(DB)

The helper functions used here make it easy to dynamically create SQL queries based on how many, and which columns we want to update
We are not really running 2 queries, but query2 represents a portion of the dynamically generated SQL - specifically the part that comes after VALUES in a typical insert SQL query.

Call the function with the name of the table you want to update, as well as the column names:

insert_sql, template_sql = create_sql('your_table', ['column1', 'column2'])

I encourage you to add print statements or breakpoints to inspect what different values look like. Below, you can see that I've printed allrows, insert_sql and template_sql to see how my dummy data will get inserted:

6. Execute the query

psycopg2.extras.execute_values(db_cusror, insert_sql, allrows, template_sql)

Note that the changes are not yet committed. This is a good checkpoint to test for errors (i.e. if you get no errors until this point, it means you're good to perform the final step).

7. Commit the changes 🎉

DB.commit()

Congratulations! You can now re-use this script to import huge amounts of data with a single command 🪄

If you have questions about any part or thoughts you want to share, feel free to mention those in the comments below :)