Build APIs with Express.js: A Beginner's Guide

Building APIs is an essential skill for web developers, and Express.js, a minimal and flexible Node.js framework, makes it easier to create robust APIs. In this guide, we'll explore how to build APIs with Express.js step-by-step, covering key concepts and providing code examples along the way.

What is Express.js?

Express.js is a web application framework for Node.js. It provides a set of features and utilities to create web applications and APIs quickly. Its lightweight nature and flexibility make it one of the most popular frameworks for backend development.

Why Use Express.js for APIs?

Minimalistic: Focuses on essential features, avoiding unnecessary complexity.
Middleware Support: Allows you to add custom middleware to handle requests and responses.
Scalable: Easily handles small and large-scale applications.
Community and Ecosystem: A large community with numerous plugins and libraries.

Prerequisites

Before starting, ensure you have:

Node.js installed on your machine.
Basic knowledge of JavaScript and Node.js.

Setting Up the Project

Initialize a New Node.js Project
```
 mkdir express-api-demo
 cd express-api-demo
 npm init -y
```
This creates a package.json file with default settings.
Install Express.js
```
 npm install express
```
Create the Entry File Create an index.js file in your project directory.

Building a Simple API

Step 1: Import and Set Up Express

Open the index.js file and write the following code:

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

// Middleware to parse JSON
app.use(express.json());

// Basic Route
app.get('/', (req, res) => {
  res.send('Welcome to the Express API!');
});

// Start the server
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

Step 2: Define API Routes

Let’s create routes for a basic To-Do List API:

GET /todos: Fetch all to-dos.
POST /todos: Add a new to-do.
PUT /todos/:id: Update an existing to-do.
DELETE /todos/:id: Delete a to-do.

Adding Routes

1. In-Memory Data Store

For simplicity, we'll use an array to store to-do items:

let todos = [
  { id: 1, task: 'Learn Express.js', completed: false },
  { id: 2, task: 'Build an API', completed: false },
];

2. GET Route: Fetch All To-Dos

Add this route to fetch the list of to-dos:

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

3. POST Route: Add a New To-Do

Add a route to create new to-do items:

app.post('/todos', (req, res) => {
  const newTodo = {
    id: todos.length + 1,
    task: req.body.task,
    completed: false,
  };
  todos.push(newTodo);
  res.status(201).json(newTodo);
});

4. PUT Route: Update an Existing To-Do

Add this route to update a to-do by its ID:

app.put('/todos/:id', (req, res) => {
  const todoId = parseInt(req.params.id, 10);
  const todo = todos.find((t) => t.id === todoId);

  if (!todo) {
    return res.status(404).json({ error: 'To-Do not found' });
  }

  todo.task = req.body.task || todo.task;
  todo.completed = req.body.completed ?? todo.completed;

  res.status(200).json(todo);
});

5. DELETE Route: Remove a To-Do

Add this route to delete a to-do:

app.delete('/todos/:id', (req, res) => {
  const todoId = parseInt(req.params.id, 10);
  const todoIndex = todos.findIndex((t) => t.id === todoId);

  if (todoIndex === -1) {
    return res.status(404).json({ error: 'To-Do not found' });
  }

  todos.splice(todoIndex, 1);
  res.status(200).json({ message: 'To-Do deleted successfully' });
});

Complete Code

Here’s the full code for your API:

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

// Middleware
app.use(express.json());

// In-Memory Data Store
let todos = [
  { id: 1, task: 'Learn Express.js', completed: false },
  { id: 2, task: 'Build an API', completed: false },
];

// Routes
app.get('/', (req, res) => {
  res.send('Welcome to the Express API!');
});

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

app.post('/todos', (req, res) => {
  const newTodo = {
    id: todos.length + 1,
    task: req.body.task,
    completed: false,
  };
  todos.push(newTodo);
  res.status(201).json(newTodo);
});

app.put('/todos/:id', (req, res) => {
  const todoId = parseInt(req.params.id, 10);
  const todo = todos.find((t) => t.id === todoId);

  if (!todo) {
    return res.status(404).json({ error: 'To-Do not found' });
  }

  todo.task = req.body.task || todo.task;
  todo.completed = req.body.completed ?? todo.completed;

  res.status(200).json(todo);
});

app.delete('/todos/:id', (req, res) => {
  const todoId = parseInt(req.params.id, 10);
  const todoIndex = todos.findIndex((t) => t.id === todoId);

  if (todoIndex === -1) {
    return res.status(404).json({ error: 'To-Do not found' });
  }

  todos.splice(todoIndex, 1);
  res.status(200).json({ message: 'To-Do deleted successfully' });
});

// Start the server
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

Testing the API

Use tools like Postman or cURL to test your API:

GET /todos: Retrieve the to-do list.
POST /todos: Add a new to-do by sending a JSON body:
```
 { "task": "Write a blog on Express.js" }
```
PUT /todos/:id: Update a to-do by ID.
DELETE /todos/:id: Remove a to-do by ID.

What’s Next?

After building your first API:

Learn Middleware: Explore custom middleware for authentication and logging.
Add Validation: Use libraries like express-validator for input validation.
Connect to a Database: Replace the in-memory data store with a database like MongoDB or PostgreSQL.
Secure Your API: Implement security practices like authentication and rate limiting.

Conclusion

Express.js simplifies the process of building APIs, even for beginners. By mastering the basics covered in this guide, you can confidently start building more complex and feature-rich applications. With time and practice, you’ll be able to scale your APIs to handle real-world use cases seamlessly. Happy coding! 🚀

A Beginner’s Guide to Building APIs with Express.js

Table of contents