How to Build a Custom REST API with Node.js and Express for Your Website

Introduction

Building a custom REST API is a fundamental skill for modern web developers. Whether you are powering a single-page application, a mobile app, or a dynamic front-end, a well-designed API acts as the backbone of your backend. In this tutorial, you will learn how to create a scalable REST API using Node.js and Express, following industry best practices. By the end, you will have a working API that you can extend for your own projects.

What is a REST API?

A REST (Representational State Transfer) API is a set of rules that allows different software applications to communicate over HTTP. It uses standard HTTP methods like GET, POST, PUT, and DELETE to perform CRUD (Create, Read, Update, Delete) operations. REST APIs are stateless, meaning each request contains all the information needed to process it, making them highly scalable.

Setting Up Your Environment

Before writing any code, ensure you have Node.js installed. You can download it from nodejs.org. Then, create a new project folder and initialize it:

mkdir my-api
cd my-api
npm init -y

Next, install Express and other dependencies:

npm install express body-parser cors

Express is a minimal web framework for Node.js, body-parser helps parse incoming request bodies, and cors enables Cross-Origin Resource Sharing.

Creating Your First Express Server

Create an index.js file and set up a basic server:

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

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

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

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

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

Run the server with node index.js and visit http://localhost:3000. You should see 'Hello World!'.

Defining API Routes

Now let's define routes for a simple resource: items. We'll use an in-memory array for data storage.

let items = [
  { id: 1, name: 'Item 1' },
  { id: 2, name: 'Item 2' }
];

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

app.get('/api/items/:id', (req, res) => {
  const item = items.find(i => i.id === parseInt(req.params.id));
  if (!item) return res.status(404).send('Item not found');
  res.json(item);
});

app.post('/api/items', (req, res) => {
  const newItem = {
    id: items.length + 1,
    name: req.body.name
  };
  items.push(newItem);
  res.status(201).json(newItem);
});

app.put('/api/items/:id', (req, res) => {
  const item = items.find(i => i.id === parseInt(req.params.id));
  if (!item) return res.status(404).send('Item not found');
  item.name = req.body.name;
  res.json(item);
});

app.delete('/api/items/:id', (req, res) => {
  const index = items.findIndex(i => i.id === parseInt(req.params.id));
  if (index === -1) return res.status(404).send('Item not found');
  items.splice(index, 1);
  res.status(204).send();
});

These routes handle all CRUD operations. Test them with a tool like Postman or curl.

Best Practices for Scalable API Development

Use Environment Variables

Store configuration like port numbers and database URLs in environment variables using a .env file and the dotenv package.

Implement Error Handling

Create a centralized error handler middleware to catch and respond to errors gracefully.

Add Input Validation

Use a library like joi or express-validator to validate request data before processing.

Structure Your Code

Organize your routes, controllers, models, and middleware into separate folders for maintainability.

Connecting to a Database

For a real application, replace the in-memory array with a database like MongoDB or PostgreSQL. For example, using Mongoose with MongoDB:

npm install mongoose

Then define a schema and model, and replace the array operations with database queries.

FAQs

What is the difference between REST and GraphQL?

REST uses fixed endpoints for resources, while GraphQL allows clients to request exactly the data they need. REST is simpler and more widely adopted for basic APIs.

How do I secure my Node.js REST API?

Use authentication (JWT, OAuth), HTTPS, input validation, and rate limiting. Also, never expose sensitive data in responses.

Can I build a REST API without Express?

Yes, you can use the built-in http module, but Express simplifies routing and middleware, making development faster.

What is the best way to test a REST API?

Use tools like Postman, Insomnia, or automated testing frameworks like Mocha and Chai with Supertest.

Conclusion

You have built a custom REST API with Node.js and Express from scratch. This foundation can be extended with databases, authentication, and more complex business logic. API development is a crucial skill for backend developers, and with practice, you can create scalable APIs that power dynamic web applications.