Building REST APIs with Node.js and Express

# CHAPTER 15

Building REST APIs with Node.js and Express #

1. Introduction #

2. Learning Objectives #

• Architect a professional folder structure for an Express API.

• Implement the Express Application instance and core middleware.

• Separate concerns using Express Routers and Controllers.

• Build standard CRUD endpoints returning JSend formatted JSON.

• Implement a Global Error Handler.

3. Beginner-Friendly Explanation #

• The Server (server.js): The building itself. It opens the doors and turns on the lights (starts listening on Port 3000).

• The App (app.js): The manager. It sets the rules: "Everyone must wear safety vests (CORS), and all boxes must be labeled (JSON Parser)."

• The Router (routes/): The conveyor belts. They inspect the label on an incoming box and route it to the correct department (e.g., "Send this to the Users department").

• The Controllers (controllers/): The workers. They receive the box, do the actual heavy lifting (database queries), and pack the result into a standardized JSON shipping box to send back.

4. Step 1: The Architecture #

rest-api/
  package.json
  server.js           <-- Bootstraps the server
  app.js              <-- Configures Express and Middleware
  routes/
    userRoutes.js     <-- Maps URLs to Controllers
  controllers/
    userController.js <-- Contains the Database Logic
  models/
    userModel.js      <-- Database Schema

5. Step 2: The Core Configuration (app.js) #

const express = require('express');
const cors = require('cors');
const userRoutes = require('./routes/userRoutes');

const app = express();

// 1. Core Middleware
app.use(cors()); // Allow cross-origin requests
app.use(express.json()); // Parse incoming JSON payloads

// 2. Mount the Routers
// All routes inside userRoutes will automatically be prefixed with /api/v1/users!
app.use('/api/v1/users', userRoutes);

// 3. Fallback Route (404)
app.all('*', (req, res) => {
    res.status(404).json({ status: "fail", message: `Can't find ${req.originalUrl}` });
});

module.exports = app;

6. Step 3: Bootstrapping the Server (server.js) #

const app = require('./app');
const PORT = process.env.PORT || 3000;

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

7. Step 4: The Routing Layer (routes/userRoutes.js) #

const express = require('express');
const userController = require('../controllers/userController');

const router = express.Router();

// Maps to: GET /api/v1/users
router.get('/', userController.getAllUsers);

// Maps to: POST /api/v1/users
router.post('/', userController.createUser);

// Maps to: GET /api/v1/users/:id
router.get('/:id', userController.getUserById);

// Maps to: DELETE /api/v1/users/:id
router.delete('/:id', userController.deleteUser);

module.exports = router;

8. Step 5: The Controller Layer (controllers/userController.js) #

let users = [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }];

exports.getAllUsers = (req, res) => {
    // Return standard JSend formatting
    res.status(200).json({
        status: "success",
        results: users.length,
        data: { users: users }
    });
};

exports.createUser = (req, res) => {
    const newUser = { id: 3, name: req.body.name };
    users.push(newUser);
    
    // 201 Created!
    res.status(201).json({
        status: "success",
        data: { user: newUser }
    });
};

exports.getUserById = (req, res) => {
    const user = users.find(u => u.id === parseInt(req.params.id));
    
    if (!user) {
        return res.status(404).json({ status: "fail", message: "User not found" });
    }
    
    res.status(200).json({
        status: "success",
        data: { user: user }
    });
};

9. Best Practices #

• Async/Await Error Wrapping: Real database calls are asynchronous (await db.find()). If a database crashes, the promise rejects, and Express will crash the entire server. You must wrap every controller function in a try/catch block, passing the error to the Global Error Handler using next(err). (Alternatively, use a package like express-async-errors to handle this automatically).

10. Common Mistakes #

• Fat Controllers: Beginners put 500 lines of complex math, API calls, and email-sending logic directly inside the Controller. Controllers should be "skinny." Their only job is to handle HTTP requests and responses. Complex logic should be extracted into separate "Service" files.

11. Exercises #

1. 1. Explain the architectural separation of concerns between userRoutes.js and userController.js. Why is the database logic removed from the routing file?

12. Coding Challenges #

• Challenge: Look at the routing layer in Step 7. Use the express.Router() object to add a new route definition for updating a user. It should map the PUT HTTP method, targeting a specific user ID, to a hypothetical controller function named updateUser.

13. MCQs with Answers #

14. Interview Questions #

• Q: Walk me through a professional folder architecture for a Node.js Express API. Detail the explicit responsibilities of the server.js, routes/, and controllers/ directories.

• Q: Explain why asynchronous database operations inside an Express Controller must be wrapped in try/catch blocks, and how caught exceptions are forwarded to a Global Error Handling middleware.

15. FAQs #

16. Summary #

17. Next Chapter Recommendation #