Glossary

144 terms from Building APIs with Node.js, in plain words, each with the chapter that teaches it.

Search the glossary

#

&& (shell operator): In a shell command, `&&` runs the second command only if the first one succeeded. `npm run check && npm test` runs the tests only when the type check passes.
.env file: A local file of environment variables that `--env-file=.env` loads. It holds the secret, so it goes in `.gitignore`.
:memory: database: A SQLite database that lives only in memory and vanishes when closed. The tests use it so every test gets a fresh, seeded database.
@fastify/cors: A Fastify plugin that sets CORS headers and answers browsers' preflight requests.
@fastify/jwt: The plugin that adds `app.jwt.sign()` to make tokens and `request.jwtVerify()` to check them.
@fastify/rate-limit: A Fastify plugin that refuses clients that send too many requests in a short time. It helps protect routes such as `/login` from password guessing and flooding.
@fastify/swagger: Plugins that collect your route schemas into an OpenAPI spec and show it as a web page at `/docs`.

A

Accept header: A request header saying which format the client wants back. `Accept: application/json` asks the server to answer in JSON.
Ajv: The package Fastify uses to check each request against your JSON Schema. Fastify also sets it up to convert types and remove extra fields.
API (Application Programming Interface): A way for programs to talk to each other. Here it means the HTTP interface of Kettle & Crane's server, which the shop and cafés call.
API key: A long random string a program sends with each request to identify itself. It is simple but never expires and says nothing about the user.
app.addHook: A Fastify call that registers a function to run at a fixed point. kc-api uses the `onClose` hook to close the database when the app closes.
app.close(): Stops the Fastify server and runs its `onClose` hooks, including closing the database. Tests and graceful shutdown both use it.
app.inject(): A Fastify method that hands a request straight to the app and returns the reply, with no network or running server involved. It is used in tests to call an API quickly and check the `statusCode`, `headers` and `json()` of the response.
app.listen(): Starts a Fastify server on a port and host. `port: 0` asks the system for any free port.
app.register(): Adds a plugin to a Fastify app, with options such as a URL prefix or the database.
as (type assertion): A TypeScript way to tell the compiler a value's type. It checks nothing at run time, so it can't replace validation.
Authentication: Checking who someone is, such as Alex proving it with a password. A failed authentication gets a 401.
Authorization: Checking what someone is allowed to do, such as Alex may change products but Sam may not. A failed authorization gets a 403.
Authorization header: The request header that carries a token as `Authorization: Bearer <token>`. `request.jwtVerify()` reads it.

B

base64url: A way of writing bytes as URL-safe letters, digits, `-` and `_`. Each part of a JWT is written this way.
beforeEach, afterEach: `node:test` hooks that run before and after every test in a file. They are typically used to build a fresh app (and database) before each test and close it afterward, so tests can't affect each other.
BEGIN, COMMIT, ROLLBACK: The SQL commands that control a transaction. `BEGIN` starts one, `COMMIT` makes the changes permanent, and `ROLLBACK` throws them away.
bigint: A JavaScript number type for very large whole numbers, written like `1n`. SQLite's `lastInsertRowid` can be one, so it is often wrapped in `Number()` to get a plain number.
Body (request/response body): The data part of a request or response, such as the JSON of a new product. Fastify parses a JSON body into `request.body`.
Buffer: Node's type for raw bytes. It is used to turn text such as hex or base64url back into bytes, for example when comparing password hashes or decoding a JWT payload.
buildApp: The function in `src/app.ts` that builds the Fastify app and database without starting a server. `server.ts` and the tests both call it.

C

Claims: The facts in a JWT's payload. `sub` is who the token is about, `iat` is when it was issued and `exp` when it expires.
Client: The program that sends requests to an API, such as the shop's website, curl or a café's app.
Collection, item: A collection is a URL for many resources, such as `/products`. An item is one of them, named by its id, such as `/products/ESP-5LB`.
Container image: A packaged copy of your app and its runtime that some hosts run instead of pulling your repository. A `Dockerfile` describes how to build one.
Content-Type: A header saying what format a body is in. `application/json` says the body is JSON.
CORS (Cross-Origin Resource Sharing): A browser rule that blocks a page on one site from calling an API on another unless the API allows it. For example, `shop.kettleandcrane.com` needs permission to call kc-api.
COUNT(*): A SQL function that counts rows. It gives the `total` for paginated lists.
CREATE TABLE: The SQL command that makes a table with typed columns. `IF NOT EXISTS` skips the work when the table is already there.
curl: A command-line program that sends one HTTP request and prints the response. `-i` shows headers, `-X` sets the method, `-H` adds a header and `-d` sends a body.
Cursor pagination: Paging by "items after this marker", such as the last SKU sent, instead of an offset. It avoids shifting pages when rows are added.

D

Database: Storage that keeps data on disk and lets many requests read and write it safely at once.
DatabaseSync: The class in Node's built-in `node:sqlite` module that opens a SQLite database. "Sync" means each call waits for the disk.
DELETE FROM: The SQL command that removes rows. Without a `WHERE` clause it deletes every row.
dependencies, devDependencies: Packages listed in `package.json`. `devDependencies`, such as `typescript`, are only needed while developing and are skipped on the server by `npm ci --omit=dev`.
Development, production: Development is running on your own computer where nobody depends on it. Production is the live system that cafés and the shop call, run by a host.
DNS record: An entry that points a domain name, such as api.kettleandcrane.com, at a server. You create one so the host serves your own domain.
Dockerfile: A text file of instructions for building a container image of your app.

E

EADDRINUSE: A Node error meaning another program is already using the port you asked for. Stop it or pick another port.
Endpoint: One method-and-path combination an API offers, such as `GET /products/:sku`.
Envelope: An object that wraps a list with facts about it, such as `{ items, total, limit, offset }`.
Environment variable: A setting supplied from outside the code, such as `PORT` or `JWT_SECRET`. On a host, the host sets them.
Error handler: A function that decides what every error turns into. kc-api's passes client errors through and hides bugs behind a plain 500.
Error shape: The fixed fields of every error reply: `statusCode`, `error` and `message`. One shape means a client needs only one piece of code to show errors.
ExperimentalWarning: A message Node prints on versions where `node:sqlite` is still experimental: it works, but details may change. The `--disable-warning=ExperimentalWarning` flag hides it.
Express: An older and widely used Node.js web framework. Its handlers answer by calling `res.json()` instead of returning a value.
extends: TypeScript syntax where one interface builds on another. `OrderLine` extends `OrderItemInput` by adding `priceCents`.

F

Fastify: A Node.js web framework for building APIs. It has validation, logging and API docs built in.
FastifyError, FastifyInstance: Fastify's TypeScript types for the app itself (`FastifyInstance`) and for an error with an optional `statusCode` (`FastifyError`).
Foreign key: A column holding another table's primary key. `order_items.order_id` points each line at its order.
format: "email": A JSON Schema keyword that checks text looks like an email address.

G

Git, .gitignore: Git tracks code changes. `.gitignore` lists files it should skip, such as `kc.db` and `.env`.
Graceful shutdown: Finishing current requests and closing the database before exiting when the host sends SIGTERM.
GraphQL: An API style with one endpoint, usually `POST /graphql`, where the client names exactly the fields it wants. It suits apps with many screens needing different data.

H

Handler: The function that answers a route's requests. In Fastify it receives `request` and `reply`.
Hash, salt: A hash is a one-way scramble of a password. A salt is random text mixed in first so identical passwords get different hashes.
Header: A name-and-value pair of extra information on a request or response, such as `Content-Type`. Names aren't case-sensitive.
Health check: A URL a host calls every few seconds to check the app still answers. Any 2xx or 3xx means healthy; an app that stops answering is restarted.
Hook, preHandler: A hook is a function Fastify runs at a fixed point in handling a request. A `preHandler` runs just before the handler and can stop the request by throwing.
Host: A company or server that runs your app for you, such as Render. It supplies settings, restarts the app and collects its logs.
Host addresses (127.0.0.1, 0.0.0.0): `127.0.0.1` is the loopback address, reachable only from the same computer; Fastify listens there by default, so kc-api stays private while you develop. `0.0.0.0` means "listen on every network interface", so on a host you set `HOST=0.0.0.0` to let outside requests reach the app.
HTTP (HyperText Transfer Protocol): The protocol clients and servers use for requests and responses, made of methods, URLs, headers, status codes and bodies.
HTTP method: The part of a request that says what the client wants done. GET reads, POST creates, PUT replaces, PATCH changes part and DELETE removes.
HttpError: A small class that extends `Error` with a `statusCode`. When a handler throws one, Fastify replies with that status in the standard error shape.
HTTPS: HTTP encrypted, so nobody between client and server can read or change it. Needed in production because tokens travel in headers.

I

Idempotency-Key: A request header carrying a unique code chosen by the client. It lets the server recognize a retried POST and return the earlier result instead of repeating the work.
Idempotent: Having the same effect whether called once or many times. Deleting NOTE-DOT twice leaves it just as deleted, but posting an order twice makes two orders.
INSERT INTO: The SQL command that adds a row to a table.
inTransaction: A helper function that runs a piece of work between `BEGIN` and `COMMIT` in the database. If the work throws, it sends `ROLLBACK` to undo every change and then rethrows the error.
ISO date text: A standard way to write a date and time as text, such as `2026-10-24T01:11:03Z`. The orders table stores `created_at` this way.

J

JSON (JavaScript Object Notation): A text format for data made of objects, arrays, strings, numbers and booleans. It is the format kc-api sends and receives.
JSON Schema: A standard way to describe what valid JSON looks like. Fastify uses it for validation, response filtering and docs.
JWT (JSON Web Token): A signed token of three base64url parts (header, payload, signature) joined by dots. It holds claims such as who the user is and when it expires; it is readable but can't be changed without detection.
JWT_SECRET: The long random secret the server uses to sign tokens. Anyone who has it can forge tokens, so it's never committed to Git.

K

kill, pid: `kill <pid>` sends SIGTERM to a process by its number, the `pid` shown in each log line.

L

lastInsertRowid: A field on the result of `.run()` that holds the id of the row just inserted.
Limit, offset: `limit` is how many items a page holds and `offset` is how many to skip first. SQL's `LIMIT ? OFFSET ?` does it.
localhost: A name for your own computer, usually 127.0.0.1. `http://localhost:3000` reaches a server running on your machine.
Location: The header giving a new resource's URL, sent with a 201 such as `/products/MUG-RED`.
LTS (Long-Term Support): A Node.js release line that gets fixes for a long time, and is the recommended kind for production.

M

mercurius: A Fastify plugin that adds a GraphQL endpoint at `/graphql` from a schema and resolvers.

N

Network interface: A connection a computer listens on. `127.0.0.1` is the loopback one, reachable only from the same machine, and others connect to real networks.
node:test: Node's built-in test runner. `node --test` finds `*.test.ts` files and runs them.
NOT NULL: A SQL column rule meaning the column can't be empty.
npm ci: Installs exactly the packages in the lockfile. `--omit=dev` skips dev dependencies, as a production server does.
npm scripts: Named commands in `package.json`. Here `dev` restarts on save, `start` runs once, `check` runs `tsc` and `test` runs the tests.

O

OpenAPI, spec: A standard for describing an HTTP API in one JSON or YAML file, the spec. Many tools read it, including Swagger UI and client generators.
ORDER BY, DESC: `ORDER BY` sorts the rows a `SELECT` returns by a column. Adding `DESC` sorts from largest to smallest.
Order status flow: The fixed path an order may follow: `new` to `paid` to `shipped`, with `cancelled` allowed from `new` or `paid`. It is stored as data in `nextStatuses`, and any other move is refused with a 409 Conflict.

P

Pagination: Returning a long list one page at a time, so each reply stays small.
Path: The part of a URL that names the resource, such as `/products/ESP-5LB`.
Persistent disk: Storage at a host that survives deploys and restarts. `DB_FILE` points into it so orders aren't wiped.
pino: The logger Fastify uses, writing one JSON object per line. Level 30 is info and 50 is error.
Placeholder: A `?` in SQL that a value fills in safely. A placeholder's value is only ever data, never SQL.
Plugin, prefix: A plugin is an `async` function that adds routes to an app. The prefix is the URL start they share, so a plugin's `/` under prefix `/products` answers `GET /products`.
Port: A number that picks which program on a computer receives a network request. kc-api uses 3000 by default.
Preflight: An `OPTIONS` request a browser sends first to ask whether a cross-origin call is allowed. The CORS plugin answers it.
Prepared statement: SQL checked once and then run many times with different values. `db.prepare()` makes one.
Primary key: The column that identifies each row, so no two rows share one. In `products` it's `sku`.
Promise: A JavaScript value for a result that will arrive later. Async functions return promises.

Q

Query string: The part of a URL after `?`, used for options such as filters (`?category=mug`). All values arrive as text.

R

Rate limiting: Refusing a client that sends too many requests, to stop password guessing or floods.
Record: A TypeScript type mapping each key to a value type. Here `Record<Status, Status[]>` makes `tsc` complain if a status is missing.
Render: A hosting service (render.com) that can run a web app such as kc-api online, with environment variables, a health check, a persistent disk and HTTPS. Other hosts need the same kinds of settings.
reply / request (Fastify): The two objects a handler receives. `request` holds what the client sent, and `reply` controls the response, with `code()`, `header()` and `send()`.
Request and response: A client sends a request (a method, URL, headers and maybe a body) and the server sends back a response (a status code, headers and usually a body).
Request id: The id Fastify gives each request and puts in its log lines as `reqId`. Searching for it links a user's report to the log.
Resolver: A GraphQL function that fetches the data for one field.
Response schema: A JSON Schema describing a reply. Fastify sends only the fields it lists, so secrets can't leak by accident, and the docs show it.
REST, resource: An API style where URLs name things and methods say what to do with them. Each thing, such as a product or order, is a resource.
Route generic: The angle-bracket type, such as `{ Params; Querystring; Body }`, that tells Fastify and TypeScript a route's request shape. It vanishes at run time.
Route, route parameter: A route is a method and path with its handler. A route parameter is a named part of the path, such as `:sku`, whose value ends up in `request.params`.

S

Safe: A method that only reads and changes nothing on the server, such as GET.
scrypt: A deliberately slow password-hashing function in `node:crypto`. The slowness makes guessing millions of passwords take too long.
Seed data: Starting rows added to an empty table, such as kc-api's products and users.
SELECT: The SQL command that reads rows. `WHERE` filters them, `ORDER BY` sorts them and `AS` renames a result column.
Set: A JavaScript collection that holds each value once. `priceItems` uses one to spot a SKU listed twice in an order.
SIGTERM: The signal a host sends to ask an app to stop, killing it outright a little later. The app can use the gap to shut down gracefully.
SKU (Stock Keeping Unit): A short product code such as ESP-5LB or MUG-BLUE that identifies one product for stock-keeping. In Kettle & Crane's API it serves as each product's id.
Spread syntax (...): JavaScript's `...` copies an object's fields or an array's values into another place. It can merge a patch over an old row, or pass an array as separate arguments such as SQL placeholder values.
SQL injection: An attack where text pasted into a query rewrites it. Passing every request value through a `?` placeholder prevents it.
SQL, SQLite: SQL is the language for working with tables of rows. SQLite is a database kept in one file, built into Node as `node:sqlite`.
Swagger UI: A web page that shows an OpenAPI spec and lets you try each endpoint. In kc-api it's at `/docs`.

T

Table: A database table holds rows with named, typed columns, such as `products`.
Test pyramid: A testing shape with many fast tests at the bottom, like the `inject` ones, and a few slow end-to-end ones on top.
timingSafeEqual: A `node:crypto` function that compares two Buffers in the same time whether they differ early or late, so timing reveals nothing.
Token: A string handed out at login that proves who the caller is. The client sends it with each request, and it carries facts about the user and expires.
Transaction: A group of database changes that all happen or none do. Placing an order is one, so a failure halfway leaves the data right.
tsc: The TypeScript compiler. Here it only type-checks and writes no JavaScript (`noEmit`), because Node runs the `.ts` files itself.
Type coercion: Converting text such as `"3"` to the type the schema asks for. It matters for query strings and route parameters, which are always text.
Type stripping: Node running `.ts` files by deleting the type annotations. It does no type checking, so types can't protect you at run time.

U

UNIQUE constraint: A database rule that no two rows share a value, such as a primary key. Breaking it makes SQLite throw an error (`errcode` 1555), which kc-api turns into a 409.
UPDATE: The SQL command that changes matching rows. Without `WHERE` it changes every row.

V

Validation: Checking a request against rules at run time, before using it. Fastify answers 400 for input that fails a schema.
Version (API version): A marker such as `/v1/` in the path that lets an API make breaking changes under a new version, such as `/v2/`.
Volume: Docker's persistent disk. You mount one so data such as the SQLite file survives container restarts.

W

Web framework: A package that handles the plumbing of routing, parsing and replies for a web server, so you write only what each URL should do.
Whitelist: A fixed list of the only choices accepted. kc-api maps allowed `sort` values to fixed SQL, since column names can't be placeholders.