REST APIs

Building a complete REST API with Express - resource-based routes, the CRUD-to-HTTP-verb mapping, status codes, and a full working example.

What it is, in plain English: A REST API exposes data as 'resources' (users, products, orders) accessible through predictable URLs and standard HTTP methods. GET reads, POST creates, PUT/PATCH updates, DELETE removes. Express's routing maps naturally onto this: app.get('/users') lists users, app.post('/users') creates one, app.get('/users/:id') reads one specific user, and so on. Following these conventions makes an API predictable to anyone who's used a REST API before.

The standard pattern for any resource

The CRUD-to-HTTP mapping

Action

HTTP Method + Route

Success Code

List all

GET /products

200

Read one

GET /products/:id

200

Create

POST /products

201

Update

PUT /products/:id

200

Delete

DELETE /products/:id

204

A complete resource, step by step

import express from "express";
const app = express();
app.use(express.json());   // needed to read req.body on POST/PUT

let products = [
  { id: 1, name: "Laptop", price: 60000 },
];
let nextId = 2;

// LIST -- GET /products
app.get("/products", (req, res) => {
  res.json(products);
});

// READ ONE -- GET /products/:id
app.get("/products/:id", (req, res) => {
  const product = products.find(p => p.id === Number(req.params.id));
  if (!product) return res.status(404).json({ error: "Not found" });
  res.json(product);
});

// CREATE -- POST /products
app.post("/products", (req, res) => {
  const product = { id: nextId++, ...req.body };
  products.push(product);
  res.status(201).json(product);
});

// UPDATE -- PUT /products/:id
app.put("/products/:id", (req, res) => {
  const product = products.find(p => p.id === Number(req.params.id));
  if (!product) return res.status(404).json({ error: "Not found" });
  Object.assign(product, req.body);
  res.json(product);
});

// DELETE -- DELETE /products/:id
app.delete("/products/:id", (req, res) => {
  products = products.filter(p => p.id !== Number(req.params.id));
  res.status(204).send();
});

app.listen(3000);

Resource naming conventions

// ✓ Use plural nouns for collections:
GET /products       (not /product or /getProducts)
GET /products/:id

// ✓ Use nested routes for relationships:
GET /users/:userId/orders        // orders belonging to a user

// ✗ Don't put verbs in the URL -- the HTTP method IS the verb:
// POST /createProduct   ✗
// POST /products          ✓ (POST already means "create")

Try It Yourself (Node.js logic)

// A complete REST API for a "todos" resource -- the standard CRUD pattern

const REST_API_EXAMPLE = `
import express from "express";
const app = express();
app.use(express.json());

let todos = [
  { id: 1, text: "Learn Express", done: false },
  { id: 2, text: "Build an API", done: false },
];
let nextId = 3;

// GET /todos -- list all (with optional filtering)
app.get("/todos", (req, res) => {
  const { done } = req.query;
  let result = todos;
  if (done !== undefined) {
    result = todos.filter(t => t.done === (done === "true"));
  }
  res.json(result);
});

// GET /todos/:id -- read one
app.get("/todos/:id", (req, res) => {
  const todo = todos.find(t => t.id === Number(req.params.id));
  if (!todo) return res.status(404).json({ error: "Todo not found" });
  res.json(todo);
});

// POST /todos -- create
app.post("/todos", (req, res) => {
  const { text } = req.body;
  if (!text?.trim()) return res.status(400).json({ error: "text is required" });

const todo = { id: nextId++, text, done: false };
  todos.push(todo);
  res.status(201).json(todo);
});

// PUT /todos/:id -- full update
app.put("/todos/:id", (req, res) => {
  const todo = todos.find(t => t.id === Number(req.params.id));
  if (!todo) return res.status(404).json({ error: "Todo not found" });

todo.text = req.body.text ?? todo.text;
  todo.done = req.body.done ?? todo.done;
  res.json(todo);
});

// DELETE /todos/:id -- remove
app.delete("/todos/:id", (req, res) => {
  const index = todos.findIndex(t => t.id === Number(req.params.id));
  if (index === -1) return res.status(404).json({ error: "Todo not found" });

todos.splice(index, 1);
  res.status(204).send();   // 204 = success, no content to return
});

app.listen(3000);
`;

console.log(REST_API_EXAMPLE.trim());

// CRUD -> HTTP method -> status code reference table:
const crudMap = [
  ["List/Read all", "GET /todos",       "200"],
  ["Read one",       "GET /todos/:id",   "200 or 404"],
  ["Create",         "POST /todos",      "201 or 400"],
  ["Full update",    "PUT /todos/:id",   "200 or 404"],
  ["Partial update", "PATCH /todos/:id", "200 or 404"],
  ["Delete",         "DELETE /todos/:id","204 or 404"],
];
console.log("\nCRUD -> REST mapping:");
crudMap.forEach(([action, route, status]) => {
  console.log(`  ${action.padEnd(16)} ${route.padEnd(20)} -> ${status}`);
});

Filtering, pagination, and partial updates

Query-based filtering and pagination

app.get("/products", (req, res) => {
  let result = [...products];

  // Filter:
  if (req.query.category) {
    result = result.filter(p => p.category === req.query.category);
  }

  // Sort:
  if (req.query.sort === "price") {
    result.sort((a, b) => a.price - b.price);
  }

  // Paginate:
  const page  = parseInt(req.query.page)  || 1;
  const limit = parseInt(req.query.limit) || 20;
  const start = (page - 1) * limit;
  const paginated = result.slice(start, start + limit);

  res.json({
    data: paginated,
    pagination: { page, limit, total: result.length, pages: Math.ceil(result.length / limit) },
  });
});
// GET /products?category=electronics&sort=price&page=2&limit=10

PATCH vs PUT -- partial vs full update

// PUT -- the client sends the COMPLETE resource, replacing it entirely:
app.put("/products/:id", (req, res) => {
  const product = findProduct(req.params.id);
  product.name = req.body.name;     // expects ALL fields
  product.price = req.body.price;
  res.json(product);
});

// PATCH -- the client sends only the fields to CHANGE:
app.patch("/products/:id", (req, res) => {
  const product = findProduct(req.params.id);
  Object.assign(product, req.body);  // merges only provided fields
  res.json(product);
});
// PATCH { price: 55000 } only changes price, leaves name/etc untouched.
// PUT with the same body would wipe out name if not included.

Nested resources

// Comments belonging to a specific post:
app.get("/posts/:postId/comments", (req, res) => {
  const comments = allComments.filter(c => c.postId === Number(req.params.postId));
  res.json(comments);
});

app.post("/posts/:postId/comments", (req, res) => {
  const comment = {
    id: nextCommentId++,
    postId: Number(req.params.postId),
    text: req.body.text,
  };
  allComments.push(comment);
  res.status(201).json(comment);
});

API versioning and HATEOAS

// URL-based versioning (most common in practice):
app.use("/api/v1/products", productsV1Router);
app.use("/api/v2/products", productsV2Router);

// Header-based versioning (less common, more "correct" per REST purists):
app.get("/products", (req, res) => {
  const version = req.headers["api-version"] || "1";
  if (version === "2") return res.json(formatV2(products));
  res.json(formatV1(products));
});

// Content negotiation via Accept header:
// Accept: application/vnd.myapi.v2+json

HATEOAS -- hypermedia links in responses (rarely fully implemented, worth knowing)

// "Hypermedia As The Engine Of Application State" -- responses include
// links to related/next actions, so clients don't need to hardcode URL structure:
app.get("/orders/:id", (req, res) => {
  const order = findOrder(req.params.id);
  res.json({
    ...order,
    _links: {
      self:    { href: `/orders/${order.id}` },
      cancel:  { href: `/orders/${order.id}/cancel`, method: "POST" },
      items:   { href: `/orders/${order.id}/items` },
    },
  });
});
// Most real-world APIs (GitHub, Stripe) implement a LIGHT version of this --
// full HATEOAS is uncommon in practice despite being part of the original REST definition.

Official Sources

The Codex links only to official documentation. No third-party tutorials.