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

An API has many callers, and they all depend on its exact behaviour: the status codes, the field names, who is allowed to do what. A small change in one route can break a mobile app that shipped months ago. **Automated tests** let you change code with confidence: you run one command, and within seconds you know whether every route still behaves as promised. Teams also review tests to understand what a route is meant to do, so a good test suite doubles as documentation.

## Kinds of tests

| Kind | What it exercises | Speed |
|---|---|---|
| **Unit** | One function, such as a validator or a price calculation | Milliseconds |
| **Integration / API** | A real request through routing, middleware, validation and a test database | Tens of milliseconds |
| **End-to-end** | A browser or app talking to a deployed stack | Seconds |

For a back end, API tests give the best value: they check the contract that clients see. Keep pure logic in unit tests, and save end-to-end tests for a few critical journeys such as signup and checkout.

## The tools

In Node, a typical setup is:

- A **test runner**: Vitest, Jest, or Node's built-in `node:test`. It finds test files, runs them and reports failures.
- A **request library**: **supertest** is the classic choice. It takes your Express `app`, sends real HTTP requests to it in memory (no port to open, no server to start) and lets you assert on the response.
- A **test database**: an in-memory SQLite database, a throwaway Docker container, or a library such as `mongodb-memory-server`. Never run tests against production data.

To make the app testable, **export it** from one file and call `listen` in another:

```javascript
// app.js
import express from "express";
export const app = express();
app.use(express.json());
app.get("/courses/:id", (req, res) => { /* ... */ });

// server.js
import { app } from "./app.js";
app.listen(process.env.PORT ?? 3000);
```

## Worked example: testing a route

```javascript
// courses.test.js
import { describe, it, expect } from "vitest";
import request from "supertest";
import { app } from "./app.js";

describe("GET /courses/:id", () => {
  it("returns the course as JSON", async () => {
    const res = await request(app).get("/courses/1");
    expect(res.status).toBe(200);
    expect(res.headers["content-type"]).toMatch(/json/);
    expect(res.body).toMatchObject({ id: 1, title: "SQL Fundamentals" });
  });

  it("returns 404 for a course that does not exist", async () => {
    const res = await request(app).get("/courses/999");
    expect(res.status).toBe(404);
  });
});

describe("POST /courses", () => {
  it("rejects a missing title with 400", async () => {
    const res = await request(app).post("/courses").send({});
    expect(res.status).toBe(400);
  });
});
```

Run it with `npx vitest` (or the `test` script in `package.json`). Each test follows **arrange, act, assert**: set up data, make one request, check the result.

## What to test for each route

A route is not tested until its failure paths are tested. For a typical route, cover:

1. **The happy path**: correct status, content type and body shape.
2. **Validation**: missing fields, wrong types and limits each give `400` (or `422`).
3. **Not found**: an unknown ID gives `404`.
4. **Authentication**: no session or token gives `401`.
5. **Authorization**: another user's object gives `403` or `404`, never the data.
6. **Side effects**: after a `POST`, a follow-up `GET` shows the new item; after a `DELETE`, it is gone.

Point 5 is the test most often missing, and it guards against the most common API vulnerability.

## Does the test actually catch bugs?

A test that always passes is worse than none, because it gives false confidence. A good trick is to **break the code on purpose**: return `200` instead of `404`, drop the ownership check, skip validation. If your tests still pass, they are not checking enough. Tools that automate this are called **mutation testing** tools; the activity in this lesson uses the same idea by hand.

## Keeping tests reliable

- **Isolate data.** Reset or reseed the test database before each test file, so tests do not depend on one another's leftovers.
- **No real network.** Stub email, payments and third-party APIs. Tests that call the internet fail randomly.
- **No sleeps.** Avoid waiting a fixed time; await the promise or poll for a condition.
- **Run them in CI** on every pull request, so a broken route never reaches `main`.
- **Measure coverage**, but treat it as a hint. 90% coverage that never checks a `401` misses the bug that matters.

## Common mistakes

- Testing only the happy path.
- Asserting on the whole response body, so any new field breaks the test. Assert on the fields that matter (`toMatchObject`).
- Starting a real server on a fixed port in tests, which clashes with other runs.
- Sharing state between tests, so they pass alone but fail together.
- Never checking that a test fails when the code is wrong.

## Quick recap

- API tests send requests through the real app and assert on status, headers and body.
- Export the Express `app` separately from `listen`, then use supertest with a test runner.
- Cover the happy path, validation, not found, `401`, the "other user" case, and side effects.
- A useful test fails when you break the code on purpose.

**Try it:** in the **Do** tab, write a test function that passes on a correct app and catches three broken ones.


Test routes through the real app with a request library, covering success, validation, auth and not-found cases.

API tests

Testing Node Server with Jest and Supertest

Create a file `openapi.yaml` with `openapi`, `info` (title, version, description) and `servers` (`http://localhost:3000`).

Add `GET /courses/{id}` with a required integer path parameter `id` (minimum 1), a `200` response and a `404` response.

Under `components/schemas`, define `Course` (`id`, `title`, `level` with an `enum` of beginner, intermediate, mid-level) and `Error` (`error` string). Reference them from the responses with `$ref`.

Add `POST /courses` with a required JSON `requestBody` using a `NewCourse` schema (`title` 1 to 100 characters, `level` enum, both in `required`), plus `201` and `400` responses.

Add `GET /courses` with an optional integer query parameter `limit` (minimum 1, maximum 100) that returns an object with an `items` array of `Course`.

Paste the file into the Swagger Editor (or open the preview) and fix every error and warning until the document validates.

Add an `example` to `Course` and look at the rendered documentation. Read it as a front-end developer would: could you call every route from it alone?

If you built the Express API in earlier lessons, compare each route and status code with your document and fix any mismatch. Commit `openapi.yaml` next to the code.

## Why it matters

Nobody can use an API they cannot understand. A front-end developer needs to know which routes exist, what to send, and what comes back, including the errors. Writing that down in a chat message or a wiki page goes stale the first time a route changes. The **OpenAPI Specification** is the industry-standard, machine-readable way to describe an HTTP API. One file can power interactive docs, generate client code and mock servers, and even validate requests in tests.

## OpenAPI and Swagger

The names are often used interchangeably:

- **OpenAPI** is the specification, maintained by the OpenAPI Initiative under the Linux Foundation. Version 3.0 and 3.1 are in wide use today.
- **Swagger** was the original name of the specification (up to version 2.0) and is now the name of a set of tools from SmartBear: Swagger Editor, Swagger UI and others.

So you write an **OpenAPI document**, and you might view it with **Swagger UI**, Redoc or Scalar.

## The shape of an OpenAPI document

An OpenAPI document is YAML or JSON. Here is a small, complete one for a course API:

```yaml
openapi: 3.1.0
info:
  title: Courses API
  version: 1.0.0
  description: Read and create courses.
servers:
  - url: http://localhost:3000
paths:
  /courses/{id}:
    get:
      summary: Get one course
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: The course
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Course"
        "404":
          description: No course with that id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /courses:
    post:
      summary: Create a course
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewCourse"
      responses:
        "201":
          description: Created
        "400":
          description: Validation failed
components:
  schemas:
    Course:
      type: object
      required: [id, title, level]
      properties:
        id: { type: integer }
        title: { type: string }
        level: { type: string, enum: [beginner, intermediate, mid-level] }
    NewCourse:
      type: object
      required: [title, level]
      properties:
        title: { type: string, minLength: 1, maxLength: 100 }
        level: { type: string, enum: [beginner, intermediate, mid-level] }
    Error:
      type: object
      properties:
        error: { type: string }
```

Reading it top to bottom:

- `info` names and versions the API.
- `servers` lists base URLs.
- `paths` lists every route. Under each path is one key per HTTP method. Path parameters use braces: `{id}`, not Express's `:id`.
- `parameters` describes path, query and header inputs, each with a `schema`.
- `requestBody` and `responses` describe bodies by content type. Response keys are status codes, quoted as strings.
- `components/schemas` holds reusable shapes, referenced with `$ref`. Schemas use JSON Schema keywords such as `type`, `required`, `enum`, `minLength` and `maximum`.

## Design-first or code-first

Teams generate the document in one of two ways:

- **Design-first**: write the OpenAPI file, agree on it with front-end and mobile developers, then implement it. Good when several teams build in parallel.
- **Code-first**: annotate your routes or schemas and generate the document from code. Some validation libraries can export their schemas as JSON Schema or OpenAPI, so your validation and your docs cannot drift apart.

Either way, keep the document in the same repository as the code and update it in the same pull request as the route change.

## What good API docs include

The specification is the reference. Add a short guide next to it that covers:

- **Authentication**: how to get a session or token, and how to send it. Describe this in OpenAPI with `securitySchemes`.
- **A quick start**: one `curl` command that works.
- **Errors**: the error body shape and what each status means.
- **Limits**: page sizes, rate limits, body size.
- **Change policy**: how versions and deprecations are announced.

Never put real credentials, internal hostnames or production data in examples. Use `example.com` addresses and obviously fake tokens.

## Common mistakes

- Documenting only the `200` response and leaving out errors.
- Docs that drift from the code because nobody updates them in the same change.
- Using Express-style `:id` in OpenAPI paths instead of `{id}`.
- Real secrets or customer data in examples.
- No `required` lists, so every field looks optional.

## Quick recap

- OpenAPI is the standard description of an HTTP API; Swagger is a family of tools for it.
- A document has `info`, `servers`, `paths` (methods, parameters, request bodies, responses) and reusable `components`.
- Document every status code a route can return, with its body shape.
- Keep the document in the repo and change it in the same pull request as the code.

**Try it:** the **Do** tab has you write and validate an OpenAPI document for two routes, using the free online Swagger Editor or a local preview.


Describe routes, inputs, responses and errors in an OpenAPI document that people and tools can read.

Documenting an API

REST API and OpenAPI: It’s Not an Either/Or Question

Understand OpenAPI in 5 Minutes With Examples

Pick a provider with a free tier for Node apps (for example a PaaS such as Render, or serverless functions on Vercel or Netlify). Read its current free-tier limits and note whether it sleeps when idle.

Prepare the app: read the port from `process.env.PORT` with a fallback, add `GET /healthz` returning `200`, add a `start` script and an `engines` field with your Node version.

Check that `.gitignore` excludes `node_modules/` and `.env`, then push the project to a GitHub repository. Look at the repository on GitHub to confirm no `.env` file is there.

Create the service in the provider's dashboard from the repository. Use `npm ci` as the build command and `npm start` as the start command (or follow the provider's guide for serverless functions).

Add any configuration (for example `GREETING`) as an environment variable in the dashboard, not in the code, and redeploy.

When the deploy finishes, run `curl -i https://<your-url>/healthz` and one real route. Confirm the status codes and that the response comes over HTTPS.

Open the provider's logs and find your requests. Make one request that fails (an unknown route) and find it in the logs too.

Push a small change (a new field in a response) and watch the platform build and deploy it automatically. Then find how to roll back to the previous deploy.

Clean up: delete the service (and any database you created) in the dashboard so nothing keeps running or billing, and confirm the URL no longer answers.

## Why it matters

An API on `localhost` only helps you. To be used by a real web page or mobile app it has to run on a server with a public HTTPS address, read its configuration from the environment, and keep running when you close your laptop. Deploying is also where a lot of "it works on my machine" bugs show up: a missing environment variable, a hard-coded port, a database that only exists locally. Shipping one small API to a free tier teaches you the whole path.

## Where an API can run

| Option | Examples | You manage | Good for |
|---|---|---|---|
| **Platform as a service (PaaS)** | Render, Railway, Fly.io, Heroku | Your code and settings | A long-running Express server |
| **Serverless functions** | Vercel Functions, Netlify Functions, AWS Lambda, Cloudflare Workers | Your handler code | Spiky or low traffic; pay per request |
| **Containers** | Docker on Google Cloud Run, AWS ECS, Azure Container Apps | A container image | Portable deployments, any runtime |
| **Virtual machine** | A VPS from any cloud | Everything: OS, updates, firewall | Full control, more work |

Free tiers change often, and some need a credit card even when they cost nothing. Read the provider's current pricing page before you sign up, and set a **budget alert** if the option exists.

**Serverless** deserves a note. Your code runs only when a request arrives, and the platform scales it for you. In exchange: the first request after idle time may be slower (a "cold start"), the local filesystem is temporary, and work should finish before the response is sent (or use the platform's "wait until" helper). Many platforms can run an Express `app` as a function with a small adapter.

## Make the app deployable

Whatever the host, a deployable Node API follows the same rules:

```javascript
// Read the port the platform gives you; fall back for local runs.
const port = Number(process.env.PORT ?? 3000);
app.listen(port, () => console.log(`Listening on ${port}`));
```

- **Configuration from environment variables**: `PORT`, `DATABASE_URL`, `JWT_SECRET`, `ALLOWED_ORIGINS`. Nothing secret in the repository.
- **A start script** in `package.json` (`"start": "node index.js"`) and the Node version in `"engines"`, so the platform uses the same version you tested.
- **A lock file**, so the build installs exactly what you tested (`npm ci`).
- **A health check route**, such as `GET /healthz` returning `200`, that the platform and your monitoring can call.
- **Persistent data elsewhere.** On most platforms the disk is wiped on each deploy, so a SQLite file next to your code will not survive. Use a hosted database (many have free tiers) and pass its URL as an environment variable.

## Worked example: the deploy loop

A typical Git-connected deploy on a PaaS looks like this:

```text
1. Push the repo to GitHub (without .env or node_modules).
2. In the provider's dashboard: New web service -> pick the repo.
3. Build command:  npm ci
   Start command:  npm start
4. Add environment variables in the dashboard (never in code).
5. Deploy. The platform builds, starts the app, and gives you
   https://your-app.example-host.com
6. Check it:  curl -i https://your-app.example-host.com/healthz
```

From now on, every push to the deploy branch triggers a new build. Many platforms also build **preview deployments** for pull requests, so you can test a change on a real URL before merging.

## After it is live

Shipping is the beginning, not the end:

- **CORS**: if a browser front end on another domain calls the API, allow that exact origin. Avoid `*` for anything that uses cookies or credentials.
- **HTTPS only**: platforms give you a certificate automatically. Set cookies with `Secure`.
- **Logs**: learn where your platform shows logs, and log errors without passwords, tokens or personal data.
- **Rollbacks**: know how to redeploy the previous version in one click when a release goes wrong.
- **Rotate secrets** if one is ever exposed, and redeploy.
- **Clean up** demo services you no longer need, so nothing keeps running (or billing) quietly.

## Common mistakes

- Hard-coding `app.listen(3000)` when the platform expects `process.env.PORT`.
- Committing `.env`, or pasting a secret into code "just for now".
- Storing data on the local disk of a serverless function or a free web service.
- Forgetting to set an environment variable in the dashboard, so the app crashes on start.
- Leaving test deployments and databases running long after the demo.

## Quick recap

- Choose a host type: PaaS for a long-running server, serverless for per-request functions, containers for portability.
- Make the app deployable: `PORT` from the environment, start script, lock file, health check, external database.
- Configure secrets in the platform, never in the repository.
- After launch, check CORS, logs and rollbacks, and clean up what you do not use.

**Try it:** the **Do** tab walks you through deploying a tiny API to a free tier and tearing it down afterwards.


Ship a Node API to a free hosting tier with environment-based config, a health check and no committed secrets.

Deploying an API

7 Ways to Deploy a Node.js App

Serverless Computing in 100 Seconds

Test routes with a request library, describe the API with OpenAPI, and deploy it to a free hosting tier.