DEV Community

Suraj Sundar
Suraj Sundar

Posted on

A Beginner’s Guide to Designing RESTful APIs in Node.js

Building scalable and maintainable APIs is a vital skill for developers in today’s software ecosystem. If you’re just starting out and wondering how to design backend APIs using Node.js and Express.js, this guide is for you.

We’ll walk through core concepts, folder structure and the reasoning behind architectural decisions — without overwhelming you with complexity.
🚀 Why Backend API Design Matters

Well-designed APIs are:
✅ Easy to understand and use
✅ Consistent and predictable
✅ Scalable as your application grows
✅ Simple to test and document

As beginners, the goal isn’t to build a massive system, but to learn how to structure clean, scalable APIs.
🛠️ Tools We’ll Use

Node.js — JavaScript runtime
Express.js — Web framework for APIs
Optional (for later scaling):
MongoDB / Postgres — For storing data
🗂️ Recommended Folder Structure

A clear project structure helps scalability and collaboration.

backend/
├── controllers/ # Logic for routes
│ └── userController.js
├── routes/ # API route definitions
│ └── userRoutes.js
├── app.js # Main server file
└── package.json

Why this structure?

Keeping route definitions and business logic in separate files makes your project easier to maintain and scale.
🧩 Why Use Controllers?

As your project grows, putting all logic inside routes becomes messy.
Separate controllers help organize the logic:

// controllers/userController.js
export const getUsers = (req, res) => {
 // logic here
};

export const addUser = (req, res) => {
 // logic here
};
Enter fullscreen mode Exit fullscreen mode

Then in your route file:

import express from ‘express’;
import { getUsers, addUser } from ‘../controllers/userController.js’;

const router = express.Router();

router.get('/', getUsers);
router.post('/', addUser);

export default router;
Enter fullscreen mode Exit fullscreen mode

✅ A Typical Beginner-Friendly Flow

Let’s say we want to:

  • GET a list of users
  • POST a new user 
// routes/userRoutes.js
router.get(‘/’, getUsers);
router.post(‘/’, addUser);
Enter fullscreen mode Exit fullscreen mode 
// controllers/userController.js
let users = [{ id: 1, name: ‘Suraj’ }];

// getUsers
export const getUsers = (req, res) => {
 try {
 res.status(200).json(users);
 } catch {
 res.status(500).json({ message: 'Server error' });
 }
};

// addUser
export const addUser = (req, res) => {
 try {
 const { name } = req.body;
 const newUser = { id: users.length + 1, name };
 users.push(newUser);
 res.status(201).json({ message: 'User created', user: newUser });
 } catch {
 res.status(500).json({ message: 'Failed to add user' });
 }
};
Enter fullscreen mode Exit fullscreen mode

🌱 How to Scale This Later?

✅ Add database support (e.g., MongoDB, PostgreSQL)
✅ Integrate authentication (JWT, OAuth)
✅ Add middleware for validation, logging, etc.
✅ Implement unit testing
✅ Use dotenv for config and secrets
✨ Final Thoughts

Your first API doesn’t need to be perfect. But with a clean structure, consistent practices, and documentation, you’ll be miles ahead.
Key Takeaways:

  • Use controllers for logic
  • Follow REST principles
  • Document your API
  • Keep code organized

If you found this helpful, share it with others or drop a comment! 🚀

Top comments (0)