REST API Design Made Simple with Express.js

APIs are how software talks to other software. A REST API is one particular style — not a protocol or a format, but a set of conventions that make APIs predictable and easy to understand. Once you learn the patterns, you can design APIs that developers actually want to use.

What REST Actually Means

REST stands for Representational State Transfer. It's not a spec you can implement — it's a set of architectural principles. The key idea: treat everything as a resource that clients interact with using standard HTTP methods.

Think of it this way: your API exposes resources (users, posts, products), and clients manipulate those resources using familiar operations. The same vocabulary works whether you're building a todo app or a massive e-commerce platform.

Resources: The Nouns of Your API

A resource is a named thing your API manages. If you're building a user management system, "users" is a resource. If you have blog posts, "posts" is a resource. Each resource maps to a URL pattern.

/users
/posts
/products

These are the nouns of your API. They're the things you're managing.

HTTP Methods: The Verbs

HTTP methods map to CRUD operations — Create, Read, Update, Delete.

A GET to /users retrieves all users. A POST to /users creates a new one. A PUT to /users/42 replaces user 42 entirely. A DELETE to /users/42 removes them.

Here's how that looks in Express:

const express = require('express');
const app = express();
app.use(express.json());

let users = [
  { id: 1, name: 'Alice', email: 'alice@example.com' },
  { id: 2, name: 'Bob', email: 'bob@example.com' }
];

// GET /users — list all users
app.get('/users', (req, res) => {
  res.json(users);
});

// GET /users/:id — get one user
app.get('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.json(user);
});

// POST /users — create a new user
app.post('/users', (req, res) => {
  const newUser = {
    id: users.length + 1,
    name: req.body.name,
    email: req.body.email
  };
  users.push(newUser);
  res.status(201).json(newUser);
});

// PUT /users/:id — replace a user
app.put('/users/:id', (req, res) => {
  const index = users.findIndex(u => u.id === parseInt(req.params.id));
  if (index === -1) return res.status(404).json({ error: 'User not found' });

  users[index] = {
    id: parseInt(req.params.id),
    name: req.body.name,
    email: req.body.email
  };
  res.json(users[index]);
});

// DELETE /users/:id — remove a user
app.delete('/users/:id', (req, res) => {
  const index = users.findIndex(u => u.id === parseInt(req.params.id));
  if (index === -1) return res.status(404).json({ error: 'User not found' });

  users.splice(index, 1);
  res.status(204).send();
});

Status Codes: The API Talking Back

Your API needs to tell the client what happened. HTTP status codes are the vocabulary:

• 200 OK — The request succeeded

• 201 Created — A new resource was created

• 204 No Content — Succeeded with no body to return (common for DELETE)

• 400 Bad Request — The client sent bad data

• 404 Not Found — The resource doesn't exist

• 500 Internal Server Error — Something broke on the server

You don't need to memorize all of them. Start with a handful and add more as needed.

Route Naming Conventions

Keep URLs lowercase and hyphenated. Use plural nouns for collections:

/active-users       ✓
/ActiveUsers        ✗
/active_users       ✗

Avoid verbs in URLs. The HTTP method is the verb:

GET /users          ✓  (don't add /getUsers)
POST /users         ✓  (don't add /createUser)

Nested resources are fine when they make sense:

GET /users/42/posts          // posts belonging to user 42
GET /users/42/posts/7        // a specific post

Wrapping Up

REST is about using HTTP as intended. Resources as nouns, methods as verbs, status codes as feedback. The conventions aren't arbitrary — they emerged from years of developers building APIs that needed to be predictable.

Express makes implementing REST APIs straightforward. Four methods, four routes per resource, status codes to communicate the result. Once the pattern clicks, you'll design clean, consistent APIs without thinking much about it.