Design REST routes, validate JSON, build Node and Express APIs on a SQL database, secure them, test them and ship them.

Back-End Web APIs

## Why it matters

Almost every app you will build talks to a server. A mobile app loads a user's feed, a web page saves a form, a dashboard pulls numbers. The server side of that conversation is an **API** (application programming interface): a set of URLs that accept requests and send back data. If the API is designed well, front-end and mobile developers can guess how it works before they read the docs. If it is designed badly, every screen needs special cases.

Most web APIs today follow a style called **REST** (representational state transfer). REST is not a library or a standard you install. It is a set of conventions built on top of HTTP, the same protocol your browser uses to load pages.

## The core idea: resources and verbs

REST splits every request into two parts:

- **The resource**: a noun, identified by a URL path. `/courses`, `/courses/42`, `/courses/42/lessons`.
- **The verb**: the HTTP method, which says what to do with that resource.

| Method | Meaning | Typical path | Changes data? |
|---|---|---|---|
| `GET` | Read | `/courses`, `/courses/42` | No |
| `POST` | Create a new item in a collection | `/courses` | Yes |
| `PUT` | Replace an item completely | `/courses/42` | Yes |
| `PATCH` | Update some fields of an item | `/courses/42` | Yes |
| `DELETE` | Remove an item | `/courses/42` | Yes |

Two properties are worth remembering:

- **Safe** methods do not change data. `GET` is safe, so browsers, caches and crawlers may call it freely. Never let a `GET` delete or update anything.
- **Idempotent** methods give the same result if you repeat them. `GET`, `PUT` and `DELETE` are idempotent: deleting item 42 twice leaves it just as deleted. `POST` is not: sending "create order" twice can create two orders. That is why payment APIs often ask for an idempotency key.

## Worked example: designing routes for a resource

Say you are building the API for a course platform, and the first resource is a **course**. Start with the nouns, then attach verbs:

```text
GET    /courses              list courses (maybe ?level=beginner&page=2)
POST   /courses              create a course (data in the request body)
GET    /courses/:id          read one course
PATCH  /courses/:id          change some fields of one course
DELETE /courses/:id          delete one course
GET    /courses/:id/lessons  list the lessons that belong to one course
```

A few habits make this predictable:

- **Plural nouns for collections.** `/courses`, not `/course` or `/getCourses`. The verb is already in the method, so do not repeat it in the path.
- **IDs in the path, filters in the query string.** `/courses/42` names one thing. `/courses?level=beginner` narrows a list. Sorting and paging (`?sort=title&page=2`) also go in the query string.
- **Nest only one level for ownership.** `/courses/42/lessons` is clear. `/schools/1/courses/42/lessons/7/comments` is painful; once a lesson has its own ID, `/lessons/7/comments` works.
- **Lowercase, hyphenated paths.** `/learning-paths`, not `/LearningPaths`.

A full request and response look like this when you run `curl -i` against a local server:

```http
GET /courses/42 HTTP/1.1
Host: localhost:3000
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 42, "title": "Back-End Web APIs", "level": "intermediate" }
```

The request line holds the method and path. **Headers** carry metadata such as `Accept` (what format the client wants) and `Content-Type` (what format the body is in). The **body** holds the data. The response starts with a **status code** (`200 OK` here), which the next lesson covers in detail.

## Actions that are not CRUD

Some operations do not fit create, read, update and delete neatly: "publish a course", "reset a password", "send a test email". Two common answers:

1. Model it as a field change: `PATCH /courses/42` with `{ "status": "published" }`.
2. Model it as creating a new resource: `POST /password-resets` with `{ "email": "..." }`. The "reset request" becomes a thing you create.

Both are fine. What you should avoid is a path full of verbs such as `POST /publishCourse?id=42`, because each one becomes a special case for every client.

## Common mistakes

- **Using GET for changes.** A link like `/courses/42/delete` can be triggered by a browser prefetch, a crawler or an image tag on another site.
- **Verbs in paths.** `/createUser`, `/getAllUsers`. Let the method carry the verb.
- **Inconsistent shapes.** If `GET /courses` returns `{ "items": [...] }`, do not make `GET /lessons` return a bare array. Pick one shape and keep it.
- **Leaking database details.** The URL is a public contract. Exposing table names or internal columns makes it hard to change your database later.
- **Changing a route that clients already use.** Once a mobile app ships, old versions keep calling the old URL for months. Add new fields and routes; remove old ones slowly, or version the API (`/v2/...`).

## Quick recap

- REST is a convention: **resources** are nouns in the URL, **methods** are verbs.
- `GET` reads and must never change data. `POST` creates, `PUT` replaces, `PATCH` updates part, `DELETE` removes.
- Use plural collections, IDs in the path, filters and paging in the query string, and shallow nesting.
- Your routes are a contract with every client. Keep them consistent and change them carefully.

Head to the **Do** tab and test yourself on route design before moving on to status codes.


Design predictable API routes by naming resources in the URL and letting HTTP methods carry the action.

REST resources and verbs

What is a REST API?

What Is REST API? Examples And How To Use It: Crash Course System Design #3

## Why it matters

Every HTTP response starts with a three-digit **status code**. Client code branches on it long before it reads the body: a mobile app shows "please log in" on a `401`, retries on a `503`, and highlights form fields on a `400`. If your API answers `200 OK` with `{ "error": "not found" }` inside, every client has to parse the body to learn that something went wrong, and tools such as monitoring dashboards, caches and retry logic will treat the failure as a success.

## The core idea: five families

The first digit tells you the family:

| Range | Family | Who should act |
|---|---|---|
| `1xx` | Informational | Rare in APIs; you can ignore them |
| `2xx` | Success | Nobody: it worked |
| `3xx` | Redirection | The client should look somewhere else |
| `4xx` | Client error | The **caller** must change the request |
| `5xx` | Server error | The **server** failed; the request may be fine |

The 4xx/5xx split is the most useful thing on this page. A `4xx` says "do not retry the same request, it will fail again". A `5xx` says "this is our fault; retrying later might work".

## The codes you will use every week

**Success**

- `200 OK`: a normal successful response with a body (`GET`, or an update that returns the new item).
- `201 Created`: a `POST` created something. Return the new item, and optionally a `Location: /courses/43` header.
- `204 No Content`: success with no body, common for `DELETE`.

**Client errors**

- `400 Bad Request`: the request is malformed or fails validation (missing field, wrong type, invalid JSON).
- `401 Unauthorized`: the caller is **not authenticated**. No session, expired token, bad credentials. The name is historical; read it as "unauthenticated".
- `403 Forbidden`: the caller **is** known but is not allowed to do this. A student trying to delete a course.
- `404 Not Found`: there is no such resource at this path.
- `409 Conflict`: the request clashes with the current state. Signing up with an email that is already taken, or approving a report that was already resolved.
- `413 Payload Too Large`: the body is bigger than the server accepts.
- `422 Unprocessable Content`: some APIs use this instead of `400` for "valid JSON, but the values break the rules". Pick one convention and stick to it.
- `429 Too Many Requests`: rate limited. Often sent with a `Retry-After` header.

**Server errors**

- `500 Internal Server Error`: an unexpected bug or crash.
- `502 Bad Gateway` / `503 Service Unavailable` / `504 Gateway Timeout`: something between the client and your code, or a service your code depends on, is down or slow.

## Worked example: choosing the code

Walk through a `PATCH /courses/42` request that renames a course:

```text
No session cookie or token           -> 401
Logged in, but role is "student"     -> 403
Course 42 does not exist             -> 404
Body is {"title": ""}                -> 400 (title must not be empty)
Title already used by another course -> 409
Database is down                     -> 503 (or 500)
Everything worked                    -> 200 with the updated course
```

Notice the **order** of the checks: authenticate first, then authorize, then look up the resource, then validate. If you validate before you authenticate, an anonymous caller can probe your rules. Some APIs return `404` instead of `403` for private items so that outsiders cannot even learn that the item exists; that is a deliberate privacy choice.

## A consistent error body

Status codes say *what kind* of failure happened; the body says *what to fix*. Choose one error shape and use it everywhere:

```json
{
  "error": "Validation failed.",
  "details": [
    { "field": "title", "message": "Title is required." }
  ]
}
```

In Express, a handler sends it like this:

```javascript
if (!title) {
  return res.status(400).json({
    error: "Validation failed.",
    details: [{ field: "title", message: "Title is required." }],
  });
}
```

Some teams follow RFC 9457 ("Problem Details for HTTP APIs"), which defines standard fields such as `type`, `title`, `status` and `detail` with the content type `application/problem+json`. That is a good default if you have no house style.

## What not to put in an error

Error messages are read by whoever calls your API, including attackers. Keep them helpful but boring:

- **No stack traces or SQL** in responses. Log them on the server instead.
- **No account enumeration.** "No user with that email" versus "Wrong password" tells an attacker which emails are registered. A login endpoint should give one message, such as "Invalid email or password.", for both.
- **No secrets** in any message, header or log line.

## Common mistakes

- **`200` for everything**, with an `error` field in the body.
- **`500` for bad input.** A missing field is the caller's mistake (`400`), not a server crash. A route that throws on bad input usually means validation is missing.
- **Mixing up `401` and `403`.** Ask: "Do we know who this is?" No means `401`; yes but not allowed means `403`.
- **Different error shapes per route**, so clients need a parser per endpoint.
- **Swallowing errors.** Catching an exception and returning `200` hides real bugs from you and your monitoring.

## Quick recap

- `2xx` worked, `4xx` the caller must change something, `5xx` the server failed.
- Learn `200`, `201`, `204`, `400`, `401`, `403`, `404`, `409`, `429` and `500` by heart.
- Check in order: authenticate, authorize, find the resource, validate, then act.
- Use one error body shape, keep messages useful, and never leak internals.

The **Do** tab has a quiz of real scenarios: pick the right code for each.


Pick the right HTTP status code for every outcome and return one consistent, safe error body.

Status codes and errors

Learn HTTP Status Codes In 10 Minutes

HTTP Status Codes Explained In 5 Minutes

## Why it matters

Your API will receive data from code you did not write: browsers, mobile apps, scripts, and people poking at it with `curl`. Some of that data will be wrong by accident, and some on purpose. **Validation** is the habit of checking every incoming value before you use it. It turns a crash or a corrupted database row into a clear `400` response that tells the caller what to fix. It is also your first line of defence against many security bugs.

## JSON in one minute

**JSON** (JavaScript Object Notation) is the standard format for API bodies. It looks like a JavaScript object literal, with stricter rules:

```json
{
  "email": "ada@example.com",
  "age": 36,
  "newsletter": true,
  "interests": ["backend", "databases"],
  "referrer": null
}
```

- Keys must be in **double quotes**. Strings use double quotes too.
- Values can be strings, numbers, `true`/`false`, `null`, arrays or objects. There is no `undefined`, no dates, no comments and no trailing commas.
- Dates travel as strings, usually ISO 8601: `"2026-10-23T14:30:00Z"`.

In JavaScript, `JSON.parse(text)` turns a JSON string into a value and `JSON.stringify(value)` does the reverse. `JSON.parse` **throws** on invalid input, so a server must catch that and answer `400`. Express's `express.json()` middleware parses the body for you and passes a syntax error to your error handler.

The client should send `Content-Type: application/json` so the server knows how to read the body:

```bash
curl -X POST http://localhost:3000/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","password":"correct horse battery"}'
```

## The core idea: never trust the body

Parsing only proves that the text is valid JSON. It says nothing about whether the **values** make sense. After `JSON.parse`, `req.body` might be:

- `null`, an array, or a number instead of an object
- missing a required field
- a field with the wrong type: `"age": "thirty"`
- a value out of range: `"age": -4`
- a string that is far too long (a 5 MB "name")
- extra fields you did not ask for, such as `"role": "admin"`

That last one matters. If a route does `db.users.insert(req.body)`, a caller can set any column they like. This bug is called **mass assignment**. The fix is to build the object you store from the fields you allow, never from the raw body.

## Worked example: a hand-written validator

Here is a validator for a signup body. It returns every problem at once, so the client can show them all:

```javascript
function validateSignup(body) {
  const errors = [];
  if (body === null || typeof body !== "object" || Array.isArray(body)) {
    return { ok: false, errors: ["Body must be a JSON object."] };
  }
  if (typeof body.email !== "string" || !body.email.includes("@")) {
    errors.push("email must be a valid email address.");
  }
  if (typeof body.password !== "string" || body.password.length < 8) {
    errors.push("password must be at least 8 characters.");
  }
  if (errors.length > 0) return { ok: false, errors };
  // Build the clean value from allowed fields only.
  return { ok: true, value: { email: body.email.trim().toLowerCase(), password: body.password } };
}
```

And the route uses it before doing anything else:

```javascript
app.post("/signup", (req, res) => {
  const result = validateSignup(req.body);
  if (!result.ok) return res.status(400).json({ error: "Validation failed.", details: result.errors });
  // From here on, use result.value, never req.body.
});
```

Note the details: `typeof` checks before string methods (calling `.includes` on a number would crash), normalising the email, and returning a new object.

## Schema libraries

Writing validators by hand gets repetitive. Most Node projects use a **schema library** such as zod, Joi or Ajv (which validates against JSON Schema). You describe the shape once and the library checks it:

```javascript
import { z } from "zod";

const Signup = z.object({
  email: z.string().trim().toLowerCase().email().max(254),
  password: z.string().min(8).max(200),
}).strict(); // reject unknown keys

const result = Signup.safeParse(req.body);
if (!result.success) return res.status(400).json({ error: "Validation failed." });
const { email, password } = result.data;
```

The same idea applies to **query strings and route parameters**. `req.params.id` is always a string, so `/courses/abc` or `/courses/-1` must be rejected before it reaches the database.

## Validate on the server, always

Front-end validation (a `required` attribute, a red border) is for the user's convenience. Anyone can skip it by calling your API directly. Server-side validation is the one that counts. Keep both, but never rely on the front end.

## Common mistakes

- **Trusting `req.body` directly**, especially passing it straight to the database.
- **Checking presence but not type.** `if (body.age)` accepts `"abc"` and rejects `0`.
- **No length limits.** Huge strings slow the server and fill the database. Cap strings and the total body size.
- **Leaking details.** "Expected string at path users[0].hash" may reveal internal structure. Keep messages about the caller's input.
- **Stopping at the first error** when the client would rather see all of them.

## Quick recap

- JSON is strict: double quotes, no comments, no `undefined`. `JSON.parse` throws on bad input.
- Parsed is not valid. Check that the body is an object, then check each field's type, range and length.
- Build the value you use from allowed fields only, to prevent mass assignment.
- Use a schema library for real projects, and validate params and queries too.

**Try it:** the **Do** tab asks you to write `validateCourse(body)` and see it tested against good and bad bodies.


Parse JSON request bodies and validate every field before your route uses it.

JSON payloads and validation

Learn JSON in 10 Minutes

Learn Zod In 30 Minutes

Design routes around resources and HTTP methods, choose the right status code for every outcome, and validate JSON request bodies.