"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: "..." }│
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
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)
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
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);
});
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
});
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);
});
PUT vs PATCH:
PUTreplaces the whole resource.PATCHupdates only the fields you send. For simplicity, most beginner APIs just usePUT.
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)
});
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)
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);
});
The key rule: Never just send
200with 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
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" } │
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
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"));
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
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)
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
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 callPUTandDELETE
Input validation — usingexpress-validatororzodto validate request bodies cleanly instead of manual checks
Error handling middleware — a centralised error handler so you don't repeatres.status(500)in every route
Router modules — splitting routes intoroutes/users.js,routes/posts.jssoapp.jsstays 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. 🚀
SOCIAL SHARE CARD GENERATOR