Skip to content
Tutorials Center
My learning

Topics

Lesson 116 of 133 ยท Projects

Project: A REST API from Scratch

Build a complete REST API in Node.js without a framework - a router with URLPattern, middleware, validation, pagination, error handling and a repository you can swap from memory to SQLite.

Frameworks such as Express, Fastify and Hono make building an API quick. But if all you ever do is call app.get(...), an API is a black box: why does a thrown error become a 500? what exactly is middleware? who decides between 400 and 422? In this project you will build a small REST API for a library of books from scratch on top of Node's http module, so that none of that is magic anymore. Everything you learn transfers directly to real frameworks, and the code you write is a surprisingly complete foundation.

You will build, in stages: a tiny router and middleware pipeline, input validation, pagination and sorting, centralized error handling, and a repository layer that lets you switch from an in-memory store to SQLite without touching the HTTP code. Background lessons: The http Module: Servers, Routing, Middleware, REST APIs and SQLite with node:sqlite.

Our editor has no npm packages, so this project uses only the standard library. URLPattern is a global in Node 24, node:sqlite is built in (and still experimental, which prints a warning on standard error), and every server listens on 127.0.0.1 with a random port and is called from the same program.

The API we are building

Method and path Meaning Success
GET /books List books (filter, sort, paginate) 200
POST /books Create a book 201
GET /books/:id Read one book 200
PUT /books/:id Replace a book completely 200
PATCH /books/:id Change some fields 200
DELETE /books/:id Delete a book 204

A book is { id, title, author, year }. The URL names the resource (a noun, plural), the method says what to do with it, and the status code reports what happened. Errors always use one JSON envelope: { "error": { "message": "...", "details": [...] } }, so clients can handle every failure in one place.

Stage 1: a router and a middleware pipeline

A framework is, at its heart, two ideas.

A router maps (method, path pattern) to a handler function and extracts parameters such as the :id in /books/:id. Node 24 ships URLPattern, which does exactly that matching, so we do not need a regular-expression compiler of our own.

Middleware are functions that wrap the handler. Each receives the request context and a next function; it can do something before, call next() to continue the chain, and do something after, with the response. Logging, authentication, timing and CORS headers are all middleware. The chain is built by recursion: dispatch(0) calls the first middleware with a next that calls dispatch(1), and so on, with the router at the end.

A handler returns a plain result object { status, body, headers } and the framework writes it. Handlers never touch res directly, which keeps them easy to test. If anything throws, the framework converts the error into a result: an HttpError becomes its own status and message, and anything else becomes a generic 500. The details of a bug are logged on the server and are never sent to the client.

Node.js A 60-line mini framework with routing and middleware

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Study the output. The route with a parameter works, the unknown path is a 404, a known path with the wrong method is a 405 (with an Allow header: HTTP requires it), and /boom shows the most important rule of error handling: the client sees only Internal Server Error, while the log has the real message. The logger middleware wraps everything and sees every final status, because errors were already converted into results by the time they travel back up the chain.

Stage 2: validating input

A REST API must assume every request is wrong until proven otherwise. Validation gives you two guarantees: the handlers only ever see data of the right shape, and the client gets precise messages. We write it as pure functions that return a list of field errors, which are trivial to test.

Two details matter. For POST and PUT all fields are required; for PATCH any field may be missing, but those present must still be valid, and an empty patch is meaningless. And unknown fields are rejected or ignored on purpose: never copy the whole request body into your store, or a client can set fields you did not intend (the classic mass assignment bug). We build a new object from the known fields only.

Node.js A pure validateBook function

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Case 4 shows mass-assignment protection: id and isAdmin simply never make it into value. In HTTP the right status for syntactically valid JSON that fails these rules is 422 Unprocessable Content (many APIs use 400; what matters is being consistent). Reserve 400 for input that cannot even be parsed.

Stage 3: pagination, sorting and filtering

GET /books returning every row is fine for ten books and a disaster for ten million. Always paginate lists. Page-based pagination (?page=3&limit=20) is the easiest for clients and works well for modest data; for huge, fast-changing data cursor-based pagination (?after=<last id>) avoids skipped or duplicated rows, but offsets are enough here.

Rules to enforce: limit has a default and a hard maximum (so no one can ask for a million rows), values must be positive integers, and the sort field must come from a whitelist. The whitelist is not optional: if the sort field ever ends up in SQL, taking it from the client unchecked is an SQL injection.

Node.js Parsing and applying paging, filter and sort

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The response should also tell the client about the paging: the total count, the number of pages, and ideally Link headers pointing to the next and previous pages. We add meta in the body and a Link header in the next stage.

Stage 4: the complete API (in-memory)

Time to assemble everything. The new idea is the repository: an object with the methods list, get, create, replace, update and remove that hides how data is stored. The HTTP handlers only talk to the repository and never know whether it is a Map or a database. All repository methods are async so a database-backed version can drop in later.

Handlers are thin: parse and validate, call the repository, build a result. Other conventions in the code below:

  • Body parsing enforces Content-Type: application/json (415 otherwise), caps the size at 64 KB (413), and reports bad JSON as 400.
  • :id(\\d+) in a route pattern means only digits match, so /books/abc is simply a 404.
  • POST returns 201 with a Location header for the new resource; DELETE returns 204 with no body; deleting something that is gone returns 404.
Node.js The books API with a client session

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

This is the whole thing: about 250 lines and no dependencies. Read the transcript against the code. Note the following:

  • Both bad POSTs that carry syntax problems (broken JSON, wrong content type) get 400 and 415; the one with wrong values gets 422 with a details array naming each field.
  • The list response has meta and a Link header with rel="next" when more pages exist.
  • PUT with a missing field is rejected, but PATCH accepts a partial body. PUT here replaces the three fields (the id never changes).
  • /boom is a 500 with a generic message for the client while the real message goes to the server log.

This API has no authentication, no rate limiting and no CORS headers. A real API exposed to the internet needs all three. Authentication and security headers are covered in Web Security Essentials, and rate limiting in Scalability and Reliability Patterns.

Stage 5: swap the store for SQLite

Because handlers only know the repository interface, moving to a real database means writing a second repository, not changing the API. How do you know the new one behaves like the old one? Run the same contract against both. A contract is a function that exercises the interface and records what it observed; if the two implementations produce identical output, they are interchangeable.

The SQLite repository demonstrates two habits: value placeholders (?) for all data, and a whitelist map for the one thing that cannot be a placeholder, the ORDER BY column.

Node.js One contract, two repositories

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The output printed is the SQLite run, and the last line proves it equals the in-memory run. In your real project the swap is a single line: createBooksApi(createSqliteRepository(db)). Notice the details a contract catches: remove must return false the second time, update of a missing id must return undefined, a case-insensitive author filter must work in both, and rows must come back as plain objects. Bugs in a repository show up here, long before they are mixed with HTTP.

Where ORDER BY ${order} comes from

Template strings in SQL are normally a red flag. Here order is built only from columns[sortBy], a value from our own constant map, plus the literal ASC or DESC. The client's text never reaches the SQL; it only selects a key. If sortBy were not in the map, columns[sortBy] would be undefined, and the query would fail loudly instead of running something dangerous. Parsing the query and rejecting unknown sort values, as parseListQuery does, is the first layer of defense, and the whitelist is the second.

What a production version adds

  • Authentication and authorization as middleware: verify a token, put the user on ctx, and check ownership in handlers.
  • Structured logging with a request id, using AsyncLocalStorage.
  • Rate limiting, timeouts and graceful shutdown: Scalability and Reliability Patterns, Graceful Shutdown and Health Checks.
  • CORS headers if browsers on other origins call the API, and Cache-Control/ETag for cacheable reads (Headers, Cookies and Caching).
  • Versioning (/v1/books) and an OpenAPI description so clients and documentation are generated from one source.
  • Idempotency keys for creating things safely under retries.
  • A real framework: now that you know what is inside one, Express, Fastify or Hono (Express) will feel familiar. Their value is the ecosystem and tested edge cases, not magic.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In the middleware pipeline, what does calling next() do?

    Each middleware decides when to continue. Code before next() runs on the way in, and code after it runs on the way out with the result.
  2. 2. Which status fits a request with valid JSON syntax but a missing required field?

    The server understood the request but the data breaks the rules. 500 is for server bugs and 404 for missing resources.
  3. 3. Why does the 500 handler send only a generic message to the client?

    Unexpected errors may contain file paths, SQL or credentials. The client gets a safe message, and you keep the real one in your logs.
  4. 4. Why should the sort query parameter be checked against a whitelist?

    Column names cannot be sent as SQL placeholders, so they must come from a trusted set, never straight from user input.
  5. 5. What is the benefit of the repository layer?

    The handlers depend on an interface. Any implementation that passes the same contract can be plugged in without touching the HTTP code.

Summary

  • A framework is a router plus a middleware pipeline; URLPattern handles path matching and parameters in Node 24.
  • Handlers return plain result objects and throw HttpError; one place converts errors to responses, and unexpected errors become a generic 500 with the details logged.
  • Validate everything: parse errors are 400, rule violations are 422, wrong content type is 415, oversized bodies are 413; copy only known fields to prevent mass assignment.
  • Paginate every list, cap limit, whitelist sort fields and return paging metadata and Link headers.
  • Hide storage behind a repository interface and prove implementations equivalent with a shared contract.
  • Use correct status codes: 201 with Location, 204 for delete, 404, and 405 with Allow.

Next: Project: Real-Time Chat Server