REST API Basics

// RESTful URL conventions for a 'users' resource:
//
// GET    /api/users       — Get all users
// GET    /api/users/42    — Get user with ID 42
// POST   /api/users       — Create a new user
// PUT    /api/users/42    — Update user 42 (full replace)
// PATCH  /api/users/42    — Partially update user 42
// DELETE /api/users/42    — Delete user 42

// Example JSON response:
{
  "status": "success",
  "data": {
    "id": 42,
    "name": "Alice",
    "email": "alice@example.com"
  }
}

// Safe: changes nothing. Things you do not control will call this, repeatedly.
app.get('/api/books/:id', getBook);

// NEVER do this — a crawler or a link preview will eventually trigger it
// app.get('/api/books/delete/:id', deleteBook);

// Idempotent: two identical calls leave the same result behind
app.put('/api/books/:id', replaceBook);      // full replacement
app.delete('/api/books/:id', deleteBook);    // gone stays gone

// NOT idempotent: two calls create two books
app.post('/api/books', createBook);

// PUT replaces — an omitted field is a request to clear it
//   PUT   /api/books/42  { "title": "Dune" }   -> author is now empty
//   PATCH /api/books/42  { "title": "Dune" }   -> only the title changed
app.patch('/api/books/:id', updateSomeFields);

// Making a create safe to retry: the client sends a key it generated
app.post('/api/orders', async (req, res) => {
  const key = req.headers['idempotency-key'];
  const existing = key && await findOrderByKey(key);
  if (existing) return res.status(200).json(existing);   // same answer as before
  // ...create the order, storing `key` alongside it
});

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

// 200 OK — Successful GET request
app.get('/api/users', (req, res) => {
  res.status(200).json({ users: [] });
});

// 201 Created — and say where the new thing now lives
app.post('/api/users', (req, res) => {
  const user = { id: 1, name: req.body.name };
  res.status(201)
     .location(`/api/users/${user.id}`)
     .json(user);
});

// 409 Conflict — the request was valid; the current state says no
app.post('/api/users/register', (req, res) => {
  return res.status(409).json({ error: 'That email is already registered' });
});

// 401 vs 403 — the two different kinds of "no"
// 401: we do not know who you are   -> the client should log in
// 403: we know, and you may not      -> logging in again will not help

// 400 Bad Request — Invalid input
app.post('/api/login', (req, res) => {
  if (!req.body.email) {
    return res.status(400).json({ error: 'Email is required' });
  }
  res.json({ message: 'Logged in' });
});

// 404 Not Found
app.get('/api/users/:id', (req, res) => {
  const user = null; // not found in DB
  if (!user) {
    return res.status(404).json({ error: 'User not found' });
  }
  res.json(user);
});

// URLs: nouns, plural, and the method carries the verb
//   GET    /api/books            list
//   POST   /api/books            create
//   GET    /api/books/42         read one
//   PATCH  /api/books/42         update some fields
//   DELETE /api/books/42         remove
//   GET    /api/users/7/books    this user's books  (one level of nesting)

// Filtering and paging live in the query string
//   GET /api/books?author=orwell&sort=-createdAt&page=2&limit=20

app.get('/api/books', async (req, res) => {
  const page  = Math.max(1, Number(req.query.page) || 1);
  const limit = Math.min(100, Number(req.query.limit) || 20);

  const { items, total } = await findBooks({ page, limit, author: req.query.author });

  res.json({
    data: items,          // an empty array when there is nothing, never null
    page,
    limit,
    total,                // without this the client cannot build a pager
    totalPages: Math.ceil(total / limit)
  });
});

// Choose the fields. Never hand a raw database row to res.json().
function toPublicUser(user) {
  return {
    id: user.id,
    name: user.name,
    email: user.email,
    createdAt: user.createdAt.toISOString()   // one date format, everywhere
  };
  // password, resetToken, isDeleted, internalNotes — deliberately absent
}

// One error shape, used by every route in the project
function fail(res, status, code, message, details) {
  return res.status(status).json({
    error: { code, message, ...(details ? { details } : {}) }
  });
}

// Validation: name the field, and say why
app.post('/api/users', (req, res) => {
  const details = [];
  if (typeof req.body.email !== 'string' || !req.body.email.includes('@')) {
    details.push({ field: 'email', message: 'A valid email is required' });
  }
  if (typeof req.body.password !== 'string' || req.body.password.length < 8) {
    details.push({ field: 'password', message: 'At least 8 characters' });
  }
  if (details.length) {
    return fail(res, 400, 'VALIDATION_FAILED', 'Some fields need attention', details);
  }
  // ...create the user
});

// The frontend branches on the CODE, never on the message text:
//   if (body.error.code === 'EMAIL_TAKEN') showEmailInUseHint();

// Versioning: add, do not rewrite
app.use('/api/v1/books', booksV1);
app.use('/api/v2/books', booksV2);   // v1 keeps working for older clients