Building RESTful APIs with Node.js and Express

Building RESTful APIs with Node.js and Express

RESTful APIs have become the standard for building web applications. They provide a flexible and scalable way to expose data and functionality to other systems, applications, or devices. In this article, we will learn how to build RESTful APIs using Node.js and the Express framework.

Node.js is a server-side JavaScript runtime that allows developers to build scalable and high-performance applications. Express is a robust and flexible Node.js web framework that provides a various feature for developing web applications and APIs.

To get started, we need to install Node.js and npm (Node Package Manager) on our machine. You can download the latest version of Node.js from the official website https://nodejs.org. Once you have installed Node.js, open your terminal and type the following command to check if Node.js and npm are installed correctly:

node -v
npm -v

The above commands will print the version of Node.js and npm installed on your machine.

Now, let’s create a new Node.js project and install the required dependencies. To do this, we need to create a new directory for our project and initialize it as a Node.js project using the following commands:

mkdir restful-api-medium
cd restful-api-medium
npm init -y

The npm init command will prompt you to answer some questions about your project, such as the project name, version, description, entry point, etc. You can leave the default options for most of the questions.

Next, let’s install the Express framework and other required dependencies using the following command:

npm install express cors body-parser

The express package is the main package for the Express framework. The body-parser package is used to parse the request body of incoming HTTP requests. The cors package is used to enable Cross-Origin Resource Sharing (CORS), which is required if you want to allow other domains to access your API.

Now, let’s create a new file called index.js in the root directory of our project and add the following code:

const express = require('express');
const bodyParser = require('body-parser');
const cors = require('cors');

const app = express();

app.use(bodyParser.json());
app.use(cors());

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Server listening on port 3000');
});

The above code creates a new Express application, sets up the middleware for parsing JSON request bodies and enabling CORS, defines a route for the root URL (/), and starts the server listening on port 3000.

Now go to your package.json file, and below script in scripts section.

"start": "node index.js",

Your package.json will look like this:

{
  "name": "restful-api-medium",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "body-parser": "^1.20.2",
    "cors": "^2.8.5",
    "express": "^4.18.2"
  }
}

To run the above code, open your terminal, navigate to the project directory, and type the following command:

npm start

This will start the server, and you should see the message Server listening on port 3000 printed in your console.

Now, if you open your web browser and go to http://localhost:3000, you should see the message Hello World! displayed on the screen.

This is just a simple example of how to create a basic web server using Express. Now, let’s learn how to build a RESTful API.

To create a RESTful API, we need to define routes for different HTTP methods (GET, POST, PUT, DELETE, etc.) and handle the requests accordingly. Let's define a simple API for managing users. We will create the following routes:

• GET /users: Returns a list of all users.
• GET /users/:id: Returns the user with the specified ID.
• POST /users: Adds a new user to the system.
• PUT /users/:id: Updates the user with the specified ID.
• DELETE /users/:id: Deletes the user with the specified ID.

Let’s implement these routes in our index.js file:

const express = require('express');
const bodyParser = require('body-parser');
const cors = require('cors');

const app = express();

app.use(bodyParser.json());
app.use(cors());

let users = [
  { id: 1, name: 'John Doe', email: 'johndoe@example.com' },
  { id: 2, name: 'Jane Doe', email: 'janedoe@example.com' },
  { id: 3, name: 'Bob Smith', email: 'bobsmith@example.com' },
];

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

app.get('/users/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const user = users.find(user => user.id === id);
  if (user) {
    res.json(user);
  } else {
    res.status(404).json({ message: 'User not found' });
  }
});

app.post('/users', (req, res) => {
  const { name, email } = req.body;
  const id = users.length + 1;
  const user = { id, name, email };
  users.push(user);
  res.status(201).json(user);
});

app.put('/users/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const userIndex = users.findIndex(user => user.id === id);
  if (userIndex !== -1) {
    const { name, email } = req.body;
    users[userIndex] = { id, name, email };
    res.json(users[userIndex]);
  } else {
    res.status(404).json({ message: 'User not found' });
  }
});

app.delete('/users/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const userIndex = users.findIndex(user => user.id === id);
  if (userIndex !== -1) {
    users.splice(userIndex, 1);
    res.status(204).send();
  } else {
    res.status(404).json({ message: 'User not found' });
  }
});

app.listen(3000, () => {
  console.log('Server listening on port 3000');
});

The above code defines the users array, which contains some sample user data. It then defines the routes for handling different HTTP requests.

The GET /users route returns the users array as JSON.

The GET /users/:id route retrieves the user with the specified ID from the users array and returns it as JSON. If the user is not found, it returns a 404 status code and a JSON message.

The POST /users route creates a new user by extracting the name and email from the request body, generating a new ID, and adding the user to the users array. It then returns the new user as JSON with a 201 status code.

The PUT /users/:id route updates the user with the specified ID by finding the user in the users array, updating its name and email properties with the data from the request body, and returning the updated user as JSON. If the user is not found, it returns a 404 status code and a JSON message.

The DELETE /users/:id route deletes the user with the specified ID by finding the user in the `users` array, removing it from the array, and returning a 204 status code (indicating success with no content). If the user is not found, it returns a 404 status code and a JSON message.

Finally, the app.listen() method starts the server and listens for incoming requests on port 3000.

Testing the API

o test our API, we can use a tool like curl or a web-based API client like Postman.

Here are some example requests we can make:

• GET /users

curl http://localhost:3000/users

Response:

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "johndoe@example.com"
  },
  {
    "id": 2,
    "name": "Jane Doe",
    "email": "janedoe@example.com"
  },
  {
    "id": 3,
    "name": "Bob Smith",
    "email": "bobsmith@example.com"
  }
]

• GET /users/2

curl http://localhost:3000/users/2

Response:

{
  "id": 2,
  "name": "Jane Doe",
  "email": "janedoe@example.com"
}

• POST /users

curl -X POST -H "Content-Type: application/json" -d '{"name": "Alice Smith", "email": "alicesmith@example.com"}' http://localhost:3000/users

Response:

{
  "id": 4,
  "name": "Alice Smith",
  "email": "alicesmith@example.com"
}

• PUT /users/3

curl -X PUT -H "Content-Type: application/json" -d '{"name": "Robert Smith", "email": "robertsmith@example.com"}' http://localhost:3000/users/3

Response:

{
  "id": 3,
  "name": "Robert Smith",
  "email": "robertsmith@example.com"
}

• DELETE /users/1

curl -X DELETE http://localhost:3000/users/1

Response:

(no content)

In this blog, we learned how to build a simple RESTful API using Node.js and Express. We started by installing the required dependencies and setting up the basic server structure. We then defined the routes for handling different HTTP requests and tested the API using curl or a web-based API client like Postman.

RESTful APIs are a powerful tool for building web applications that can communicate with each other and exchange data. With Node.js and Express, it’s easy to create robust, scalable APIs that can handle a variety of requests and respond with JSON data.

There are many more features and concepts to explore when it comes to building RESTful APIs with Node.js and Express, such as middleware, authentication, and database integration. However, this tutorial provides a solid foundation for building your own APIs and can serve as a starting point for further exploration.

As you continue to build and refine your APIs, it’s important to keep in mind the principles of RESTful design, such as using HTTP verbs and status codes appropriately, using resource-oriented URLs, and keeping the API stateless.

It’s also important to consider security best practices, such as implementing authentication and authorization mechanisms, handling input validation and sanitization, and protecting against common attacks like SQL injection and cross-site scripting (XSS).

Overall, building RESTful APIs with Node.js and Express can be a rewarding and powerful way to build web applications that can interact with a wide range of other services and platforms. With the right tools and knowledge, you can create APIs that are fast, scalable, and easy to use, enabling you to create robust and flexible web applications that meet the needs of your users.

In addition to the basic concepts covered in this tutorial, there are many additional topics you may want to explore as you build more complex APIs. Here are a few examples:

Middleware

Middleware functions are functions that can be invoked by an Express route handler before or after the main route handler function is called. Middleware functions can be used to modify request and response objects, handle errors, or perform other tasks.

Here’s an example of a middleware function that logs the request method and URL:

app.use((req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
});

In this example, the app.use() method is used to register a middleware function that logs the request method and URL to the console. The next() function is called to pass control to the next middleware function in the chain.

Authentication and Authorization

Authentication and authorization are important considerations when building APIs that require secure access. There are many ways to implement authentication and authorization, but some common techniques include:

• Token-based authentication, where clients obtain a token that they use to authenticate subsequent requests
• OAuth2, a protocol for delegating authorization from one system to another
• Basic authentication, where clients include a username and password in each request

Here’s an example of a basic authentication middleware function:

const auth = (req, res, next) => {
  const authHeader = req.headers.authorization;
  if (!authHeader) {
    return res.status(401).json({ message: 'Authorization header missing' });
  }
  const [type, token] = authHeader.split(' ');
  if (type !== 'Bearer') {
    return res.status(401).json({ message: 'Invalid authorization type' });
  }
  if (token !== 'my-secret-token') {
    return res.status(401).json({ message: 'Invalid token' });
  }
  next();
};

In this example, the middleware function checks for the presence of an authorization header in the request, and verifies that the header is of the expected type and contains a valid token. If the token is valid, the middleware function calls the next() function to pass control to the next middleware function or route handler.

Database Integration

Many APIs require integration with a database to store and retrieve data. There are many databases that can be used with Node.js and Express, including relational databases like MySQL and PostgreSQL, NoSQL databases like MongoDB and CouchDB, and in-memory databases like Redis and Memcached.

Here’s an example of using the pg module to connect to a PostgreSQL database:

const { Pool } = require('pg');

const pool = new Pool({
  user: 'myuser',
  host: 'localhost',
  database: 'mydb',
  password: 'mypassword',
  port: 5432,
});

const getUsers = async () => {
  const { rows } = await pool.query('SELECT * FROM users');
  return rows;
};

In this example, the pg module is used to create a connection pool to a PostgreSQL database. The getUsers() function uses the pool.query() method to execute a SQL query and return the results.

Conclusion

In this tutorial, we covered the basics of building RESTful APIs with Node.js and Express. We started by installing the necessary dependencies and creating a basic server structure. We then defined routes for handling different HTTP requests and tested the API using a tool like curl or a web-based API client like Postman.

We also covered some additional topics that you may want to explore as you build more complex APIs, such as middleware, authentication and authorization, and database integration.

Building APIs can be a challenging but rewarding task and Node.js and Express provide a powerful platform for building fast, scalable, and flexible APIs. By following best practices and staying up-to-date on new technologies and techniques, you can create APIs that meet the needs of your users and enable you to build robust and flexible web applications.

As you continue to work with Node.js and Express, be sure to explore the many resources available online, such as documentation, tutorials, and forums. And don’t be afraid to experiment and try new things — building APIs is a dynamic and constantly evolving field, and there are always new ideas and approaches to explore.

Hope you find this article insightful 😉 💚

✨ Follow me on -

YouTube — https://www.youtube.com/@theritikchoure/

LinkedIn — https://www.linkedin.com/in/ritikchourasiya/

Twitter — https://twitter.com/theritikchoure

Get complete code — theritikchoure/restful-api-medium (github.com)