Building a RESTful API with Node.js and Express | Complete 2025 Guide

RESTful APIs have become the standard for building scalable web services. They provide a clean, stateless architecture that's easy to scale and maintain. This comprehensive guide will walk you through creating a production-ready RESTful API using Node.js and Express.

REST Architecture Principles

REST (Representational State Transfer) follows these key principles:

1. Stateless – Each request contains all necessary information
2. Client-Server – Separation of concerns
3. Cacheable – Responses must define themselves as cacheable
4. Uniform Interface – Consistent design patterns
5. Layered System – Multiple layers of architecture
6. Code on Demand (optional) – Server can extend functionality

Common HTTP Methods

• GET – Retrieve resources
• POST – Create new resources
• PUT – Update entire resources
• PATCH – Partial updates
• DELETE – Remove resources

Prerequisites

# Check Node.js version (v18+ recommended)
node --version
# Check npm version
npm --version

Project Initialization

# Create project directory
mkdir my-api
cd my-api
# Initialize package.json
npm init -y
# Install dependencies
npm install express mongoose dotenv cors helmet morgan
# Install dev dependencies
npm install nodemon

Basic Server Setup

// server.js
const express = require('express');
const mongoose = require('mongoose');
const cors = require('cors');
const helmet = require('helmet');
const morgan = require('morgan');
require('dotenv').config();
const app = express();
// Middleware
app.use(helmet()); // Security headers
app.use(cors()); // Enable CORS
app.use(express.json()); // Parse JSON
app.use(express.urlencoded({ extended: true }));
app.use(morgan('dev')); // Logging
// Database connection
mongoose.connect(process.env.MONGODB_URI)
  .then(() => console.log('MongoDB connected'))
  .catch(err => console.error(err));
// Routes
app.use('/api/v1/products', require('./routes/products'));
// Error handling
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ error: 'Something went wrong!' });
});
const PORT = process.env.PORT || 5000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Route Structure

Organize routes by resource:

// routes/products.js
const express = require('express');
const router = express.Router();
const {
  getProducts,
  getProduct,
  createProduct,
  updateProduct,
  deleteProduct
} = require('../controllers/products');
router.route('/')
  .get(getProducts)
  .post(createProduct);
router.route('/:id')
  .get(getProduct)
  .put(updateProduct)
  .patch(updateProduct)
  .delete(deleteProduct);
module.exports = router;

Controller Logic

// controllers/products.js
const Product = require('../models/Product');
// @desc    Get all products
// @route   GET /api/v1/products
// @access  Public
exports.getProducts = async (req, res, next) => {
  try {
    const products = await Product.find();
    res.status(200).json({
      success: true,
      count: products.length,
      data: products
    });
  } catch (error) {
    next(error);
  }
};
// @desc    Get single product
// @route   GET /api/v1/products/:id
// @access  Public
exports.getProduct = async (req, res, next) => {
  try {
    const product = await Product.findById(req.params.id);
    if (!product) {
      return res.status(404).json({
        success: false,
        message: 'Product not found'
      });
    }
    res.status(200).json({
      success: true,
      data: product
    });
  } catch (error) {
    next(error);
  }
};

Authentication Middleware

// middleware/auth.js
const jwt = require('jsonwebtoken');
exports.protect = async (req, res, next) => {
  let token;
  if (req.headers.authorization?.startsWith('Bearer')) {
    token = req.headers.authorization.split(' ')[1];
  }
  if (!token) {
    return res.status(401).json({
      success: false,
      message: 'Not authorized to access this route'
    });
  }
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = await User.findById(decoded.id);
    next();
  } catch (error) {
    return res.status(401).json({
      success: false,
      message: 'Not authorized'
    });
  }
};
exports.authorize = (...roles) => {
  return (req, res, next) => {
    if (!roles.includes(req.user.role)) {
      return res.status(403).json({
        success: false,
        message: 'Not authorized'
      });
    }
    next();
  };
};

Error Handling Middleware

// middleware/errorHandler.js
const errorHandler = (err, req, res, next) => {
  let error = { ...err };
  error.message = err.message;
  // Mongoose bad ObjectId
  if (err.name === 'CastError') {
    const message = 'Resource not found';
    error = { message, statusCode: 404 };
  }
  // Mongoose duplicate key
  if (err.code === 11000) {
    const message = 'Duplicate field value entered';
    error = { message, statusCode: 400 };
  }
  // Mongoose validation error
  if (err.name === 'ValidationError') {
    const message = Object.values(err.errors).map(val => val.message);
    error = { message, statusCode: 400 };
  }
  res.status(error.statusCode || 500).json({
    success: false,
    message: error.message || 'Server Error'
  });
};
module.exports = errorHandler;

MongoDB with Mongoose

// models/Product.js
const mongoose = require('mongoose');
const productSchema = new mongoose.Schema({
  name: {
    type: String,
    required: [true, 'Please add a name'],
    unique: true,
    trim: true
  },
  description: {
    type: String,
    required: [true, 'Please add a description']
  },
  price: {
    type: Number,
    required: [true, 'Please add a price'],
    min: 0
  },
  category: {
    type: String,
    enum: ['Electronics', 'Clothing', 'Books', 'Other'],
    default: 'Other'
  },
  createdAt: {
    type: Date,
    default: Date.now
  }
});
module.exports = mongoose.model('Product', productSchema);

Data Validation

// Validation example
const Joi = require('joi');
const productValidationSchema = Joi.object({
  name: Joi.string().required().min(3).max(50),
  description: Joi.string().required().min(10),
  price: Joi.number().required().min(0),
  category: Joi.string().valid('Electronics', 'Clothing', 'Books', 'Other')
});
exports.validateProduct = (req, res, next) => {
  const { error } = productValidationSchema.validate(req.body);
  if (error) {
    return res.status(400).json({
      success: false,
      message: error.details[0].message
    });
  }
  next();
};

1. Versioning Your API

/api/v1/products
/api/v2/products

2. Pagination

// GET /api/v1/products?page=1&limit=10
const page = parseInt(req.query.page) || 1;
const limit = parseInt(req.query.limit) || 10;
const skip = (page - 1) * limit;
const products = await Product.find().skip(skip).limit(limit);

3. Filtering & Sorting

// Filtering
const queryObj = { ...req.query };
const excludeFields = ['page', 'sort', 'limit'];
excludeFields.forEach(field => delete queryObj[field]);
let query = Product.find(queryObj);
// Sorting
if (req.query.sort) {
  const sortBy = req.query.sort.split(',').join(' ');
  query = query.sort(sortBy);
}

4. Rate Limiting

const rateLimit = require('express-rate-limit');
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests per windowMs
});
app.use('/api', limiter);

5. API Documentation

Use tools like:

• Swagger/OpenAPI – Interactive documentation
• Postman – API testing
• Insomnia – Alternative to Postman

What's the difference between REST and GraphQL?

REST:

• Multiple endpoints
• Over-fetching/under-fetching
• Simple caching
• Better for standard CRUD GraphQL:
• Single endpoint
• Precise data fetching
• Complex caching
• Better for complex data needs

How do I secure my API?

1. HTTPS only – Encrypt all traffic
2. Authentication – JWT, OAuth
3. Rate limiting – Prevent abuse
4. Input validation – Sanitize all inputs
5. SQL injection prevention – Use ORM/parameterized queries
6. CORS configuration – Control access
7. Helmet.js – Security headers

What database should I use?

MongoDB:

• Flexible schema
• Great for prototypes
• JSON documents
• Scales horizontally PostgreSQL:
• Rigid schema
• ACID compliance
• Complex queries
• Better for relational data

How do I handle file uploads?

const multer = require('multer');
const upload = multer({
  storage: multer.diskStorage({
    destination: './uploads/',
    filename: (req, file, cb) => {
      cb(null, file.fieldname + '-' + Date.now());
    }
  }),
  limits: { fileSize: 1000000 } // 1MB
});
app.post('/upload', upload.single('file'), (req, res) => {
  res.send({ file: req.file });
});

API Performance

Optimize your API for speed:

• Gzip compression
• Minimize payload size
• Use pagination
• Implement caching
• CDN for static assets
• Database indexing

API Security Checklist

• HTTPS enabled
• Rate limiting configured
• Input validation implemented
• Authentication required for sensitive routes
• CORS properly configured
• Security headers (Helmet.js)
• Environment variables for secrets
• Regular dependency updates
• API key rotation policy
• Error logging without sensitive data

At Giopio, we build APIs that power your business:

• Scalable Architecture – Grows with your needs
• Security First – Enterprise-grade security
• Performance Optimized – Lightning-fast responses
• Best Practices – Industry standards
• Documentation – Clear, comprehensive docs
• Support & Maintenance – Ongoing assistance
• Integration Support – Third-party services

Contact Giopio for professional API development. 📍 USA API Development | 🌐 Building scalable solutions nationwide

Related Services: Backend Development, Database Design, Cloud Integration, API Integration