Express.js로 간단해진 REST API 디자인

“An API is a contract between your server and everyone who wants to talk to it. REST is the language that contract is written in.”

Introduction

Every time your frontend fetches a list of users, a mobile app submits a form, or one service talks to another — that communication happens through an API. And the most widely adopted style for building those APIs is REST.

REST isn’t a library or a framework. It’s a set of conventions — a shared language for structuring how clients and servers communicate. Express.js is the tool that makes implementing those conventions in Node.js clean and fast.

By the end of this guide you’ll understand what REST means, how HTTP methods map to actions, how to name your routes correctly, and how to build a complete set of user endpoints with Express.

1. What REST API Means

REST stands for Representational State Transfer. Ignore the academic name — what it actually means in practice is a simple set of rules for how a client (a browser, a mobile app, another server) communicates with your server over HTTP.

APIs as Communication

Think of an API as a waiter in a restaurant:

CLIENT                        SERVER
(diner)                    (kitchen)

  │  "I'd like the user     │
  │   with ID 42, please"   │
  │ ──────────────────────► │
  │                         │  looks up user 42
  │                         │  prepares a response
  │ ◄────────────────────── │
  │  Here's your user:      │
  │  { id: 42, name: "..." }│

Enter fullscreen mode Exit fullscreen mode

The client doesn’t know how the kitchen works. It just sends a request in the right format and expects a response. The API is the menu that defines what requests are valid and what responses look like.

What Makes an API “RESTful”

A REST API follows these core principles:

Resources over actions — You describe things (users, orders, products), not verbs (getUser, createOrder). The action is expressed by the HTTP method, not the URL.

Stateless — Every request contains all the information the server needs. The server holds no session between requests.

Uniform interface — Consistent URL patterns and HTTP methods mean any developer can predict how your API works without reading every endpoint’s documentation.

2. Resources in REST Architecture

The most important concept in REST is the resource. A resource is any piece of data your API exposes — a user, a post, a product, an order.

In REST, resources are represented as nouns in the URL:

✅ CORRECT — noun-based resources
/users
/users/42
/users/42/posts

❌ WRONG — verb-based URLs (not RESTful)
/getUser
/createUser
/deleteUserById
/fetchAllPosts

Enter fullscreen mode Exit fullscreen mode

The URL tells you what you’re working with. The HTTP method tells you what you want to do with it.

Two URL Patterns

Every resource has two URL patterns:

COLLECTION       →  /users         (all users)
SINGLE RESOURCE  →  /users/:id     (one specific user)

Enter fullscreen mode Exit fullscreen mode

This simple pattern covers every operation you’ll ever need.

3. HTTP Methods: The Four Pillars of REST

HTTP methods are the verbs that act on your noun-based resources. Four cover the overwhelming majority of what any API needs to do.

HTTP METHOD  │  ACTION        │  SQL EQUIVALENT  │  CRUD
─────────────┼────────────────┼──────────────────┼────────
GET          │  Read          │  SELECT           │  Read
POST         │  Create        │  INSERT           │  Create
PUT          │  Update        │  UPDATE           │  Update
DELETE       │  Remove        │  DELETE           │  Delete

Enter fullscreen mode Exit fullscreen mode

GET — Fetch Data

GET retrieves data. It should never change anything on the server. It’s safe to call multiple times with the same result.

// Get all users
app.get("/users", async (req, res) => {
  const users = await db.getAll();
  res.status(200).json(users);
});

// Get a specific user
app.get("/users/:id", async (req, res) => {
  const user = await db.getById(req.params.id);
  res.status(200).json(user);
});

Enter fullscreen mode Exit fullscreen mode

POST — Create a Resource

POST creates a new resource. The data for the new resource comes in the request body. The server decides the new resource’s ID.

// Create a new user
app.post("/users", async (req, res) => {
  const { name, email } = req.body;
  const newUser = await db.create({ name, email });
  res.status(201).json(newUser); // 201 = Created
});

Enter fullscreen mode Exit fullscreen mode

PUT — Update a Resource

PUT updates an existing resource. It typically replaces the entire resource with the new data sent in the body.

// Update (replace) a user
app.put("/users/:id", async (req, res) => {
  const { name, email } = req.body;
  const updatedUser = await db.update(req.params.id, { name, email });
  res.status(200).json(updatedUser);
});

Enter fullscreen mode Exit fullscreen mode

PUT vs PATCH: PUT replaces the whole resource. PATCH updates only the fields you send. For simplicity, most beginner APIs just use PUT.

DELETE — Remove a Resource

DELETE removes a resource. The server deletes it and typically responds with either the deleted item or nothing (just a status code).

// Delete a user
app.delete("/users/:id", async (req, res) => {
  await db.delete(req.params.id);
  res.status(204).send(); // 204 = No Content (success, nothing to return)
});

Enter fullscreen mode Exit fullscreen mode

4. Status Codes: Communicating What Happened

HTTP status codes are the server’s way of telling the client what happened to its request. They’re three-digit numbers grouped by category.

The Categories

1xx → Informational   (rare in APIs)
2xx → Success         (request worked)
3xx → Redirection     (go look elsewhere)
4xx → Client error    (you did something wrong)
5xx → Server error    (we did something wrong)

Enter fullscreen mode Exit fullscreen mode

The Codes You’ll Actually Use

Code Name When to use 200 OK Successful GET, PUT 201 Created Successful POST — new resource made 204 No Content Success, nothing to return (DELETE) 400 Bad Request Request body is malformed or missing fields 401 Unauthorized No valid authentication provided 403 Forbidden Authenticated, but not allowed to do this 404 Not Found Resource doesn’t exist 409 Conflict Resource already exists (duplicate email) 500 Internal Server Error Something broke on the server

In Practice

app.get("/users/:id", async (req, res) => {
  const user = await db.getById(req.params.id);

  if (!user) {
    return res.status(404).json({ error: "User not found" });
    //                   ^^^  Tell the client WHY it failed
  }

  res.status(200).json(user);
});

Enter fullscreen mode Exit fullscreen mode

The key rule: Never just send 200 with an error message in the body. Use the actual status code — that’s how clients (and developers) know what happened without reading the response body.

5. Designing REST Routes

Good REST route design is consistent, predictable, and readable. Here are the conventions that make routes instantly understandable.

URL Convention Rules

RULE 1 — Always use plural nouns
  ✅  /users      ❌  /user
  ✅  /products   ❌  /product

RULE 2 — Use kebab-case for multi-word resources
  ✅  /blog-posts   ❌  /blogPosts   ❌  /blog_posts

RULE 3 — No verbs in URLs (the method IS the verb)
  ✅  DELETE /users/42       ❌  POST /deleteUser/42
  ✅  POST   /users          ❌  GET  /createUser

RULE 4 — Nest for sub-resources (but max 2 levels deep)
  ✅  /users/42/posts         (posts belonging to user 42)
  ✅  /users/42/posts/7       (post 7 belonging to user 42)
  ❌  /users/42/posts/7/comments/3/likes   (too deep)

RULE 5 — Query strings for filtering, sorting, pagination
  ✅  GET /users?role=admin
  ✅  GET /users?sort=createdAt&order=desc
  ✅  GET /users?page=2&limit=20

Enter fullscreen mode Exit fullscreen mode

The Request-Response Lifecycle

CLIENT                                           SERVER
  │                                                │
  │   GET /users/42                                │
  │   Headers: { Authorization: "Bearer ..." }     │
  │ ─────────────────────────────────────────────► │
  │                                                │  1. Parse URL → extract id: 42
  │                                                │  2. Run middleware (auth check)
  │                                                │  3. Hit route handler
  │                                                │  4. Query database
  │                                                │  5. Build response
  │                                                │
  │ ◄───────────────────────────────────────────── │
  │   Status: 200 OK                               │
  │   Content-Type: application/json               │
  │   Body: { "id": 42, "name": "Alice", ... }     │
  │                                                │
  │   (or on failure)                              │
  │                                                │
  │ ◄───────────────────────────────────────────── │
  │   Status: 404 Not Found                        │
  │   Body: { "error": "User not found" }          │

Enter fullscreen mode Exit fullscreen mode

6. Example Resource: Users

Let’s bring everything together and build a complete, RESTful users API with Express.

The Route Map

METHOD   ROUTE           ACTION               BODY REQUIRED?
──────────────────────────────────────────────────────────
GET      /users          List all users        No
GET      /users/:id      Get one user          No
POST     /users          Create a user         Yes
PUT      /users/:id      Update a user         Yes
DELETE   /users/:id      Delete a user         No

Enter fullscreen mode Exit fullscreen mode

The Full Implementation

const express = require("express");
const app = express();

// Parse incoming JSON bodies
app.use(express.json());

// ── In-memory data store (replace with a real DB) ─────────
let users = [
  { id: 1, name: "Alice", email: "[email protected]", role: "admin"  },
  { id: 2, name: "Bob",   email: "[email protected]",   role: "editor" },
  { id: 3, name: "Carol", email: "[email protected]", role: "viewer" }
];
let nextId = 4;

// ── GET /users ────────────────────────────────────────────
app.get("/users", (req, res) => {
  let result = users;
  if (req.query.role) {
    result = users.filter(u => u.role === req.query.role);
  }
  res.status(200).json(result);
});

// ── GET /users/:id ────────────────────────────────────────
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.status(200).json(user);
});

// ── POST /users ───────────────────────────────────────────
app.post("/users", (req, res) => {
  const { name, email, role } = req.body;

  if (!name || !email) {
    return res.status(400).json({ error: "Name and email are required" });
  }

  const exists = users.find(u => u.email === email);
  if (exists) {
    return res.status(409).json({ error: "Email already in use" });
  }

  const newUser = { id: nextId++, name, email, role: role || "viewer" };
  users.push(newUser);
  res.status(201).json(newUser);
});

// ── PUT /users/:id ────────────────────────────────────────
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" });

  const { name, email, role } = req.body;
  if (!name || !email) {
    return res.status(400).json({ error: "Name and email are required" });
  }

  users[index] = { id: users[index].id, name, email, role: role || users[index].role };
  res.status(200).json(users[index]);
});

// ── DELETE /users/:id ─────────────────────────────────────
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();
});

app.listen(3000, () => console.log("API running at http://localhost:3000"));

Enter fullscreen mode Exit fullscreen mode

Testing with curl

# List all users
curl http://localhost:3000/users

# Filter by role
curl "http://localhost:3000/users?role=admin"

# Get one user
curl http://localhost:3000/users/1

# Create a user
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Dave","email":"[email protected]","role":"editor"}'

# Update a user
curl -X PUT http://localhost:3000/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice Smith","email":"[email protected]","role":"admin"}'

# Delete a user
curl -X DELETE http://localhost:3000/users/2

Enter fullscreen mode Exit fullscreen mode

What Each Response Looks Like

GET /users           → 200  [ { id, name, email, role }, ... ]
GET /users/1         → 200  { id: 1, name: "Alice", ... }
GET /users/999       → 404  { error: "User not found" }
POST /users          → 201  { id: 4, name: "Dave", ... }
POST /users (no email) → 400  { error: "Name and email are required" }
POST /users (dupe)   → 409  { error: "Email already in use" }
PUT /users/1         → 200  { id: 1, name: "Alice Smith", ... }
DELETE /users/2      → 204  (empty body)

Enter fullscreen mode Exit fullscreen mode

CRUD → HTTP Method Mapping

ACTION      │  METHOD  │  ROUTE        │  SUCCESS CODE
────────────┼──────────┼───────────────┼──────────────
Read all    │  GET     │  /users       │  200 OK
Read one    │  GET     │  /users/:id   │  200 OK
Create      │  POST    │  /users       │  201 Created
Update      │  PUT     │  /users/:id   │  200 OK
Delete      │  DELETE  │  /users/:id   │  204 No Content
────────────┼──────────┼───────────────┼──────────────
Not found   │  any     │  /users/:id   │  404 Not Found
Bad body    │  POST/PUT│  /users       │  400 Bad Request
Duplicate   │  POST    │  /users       │  409 Conflict

Enter fullscreen mode Exit fullscreen mode

Quick Reference

Concept Rule URL naming Plural nouns: /users, /products Multi-word Kebab-case: /blog-posts No verbs in URLs The HTTP method is the verb Sub-resources Nest up to 2 levels: /users/:id/posts Filtering / paging Query strings: ?role=admin&page=2 Successful GET 200 OK + data Successful POST 201 Created + new resource Successful DELETE 204 No Content Resource not found 404 Not Found + error message Invalid body 400 Bad Request + error message

Key Takeaways

• REST is a set of conventions for how clients and servers communicate over HTTP — not a library
• Resources are nouns in URLs; HTTP methods are the verbs that act on them
• The four HTTP methods — GET, POST, PUT, DELETE — map directly to Read, Create, Update, Delete
• Status codes tell clients what happened without reading the response body — use them correctly
• URL design: plural nouns, no verbs, kebab-case, max 2 nesting levels
• Query strings handle filtering, sorting, and pagination — not new endpoints

What’s Next?

With a solid REST API foundation, natural next steps include:

• Authentication middleware — protecting routes with JWT tokens so only authorised users can call PUT and DELETE
• Input validation — using express-validator or zod to validate request bodies cleanly instead of manual checks
• Error handling middleware — a centralised error handler so you don’t repeat res.status(500) in every route
• Router modules — splitting routes into routes/users.js, routes/posts.js so app.js stays clean as the API grows
• Database integration — swapping the in-memory array for a real database like PostgreSQL, MongoDB, or SQLite

REST is the foundation every backend developer needs. Master these conventions and every API — whether you’re building it or consuming it — will make immediate sense.

Next up: securing your REST API with JWT authentication — adding an auth middleware that turns your open endpoints into protected resources. 🚀