REST API with Typed Validation in Node.js
A small resource API with schema-validated requests, uniform error bodies and generated OpenAPI docs.
- Runs out of the box: yes
- Tests: yes
- CI: yes
- Docs: yes
- Used in production: no
Purpose#
The first of three implementations of the same "work orders" API. Requests are parsed with Zod schemas, handlers receive typed data only, and every error leaves the service as one JSON shape with a stable code.
The three implementations share an OpenAPI description and the same acceptance tests, so request validation, pagination and error handling can be compared line by line across languages.
What you will learn#
- Validate request bodies, queries and path parameters with one schema per route
- Return a single error body shape with stable machine-readable codes
- Run the shared acceptance suite against a new implementation
Technologies & features#
- Technologies
- TypeScriptNode.jsZodPostgreSQL
- Features
- REST API DesignEnvironment Configuration
- Topics
- Application Architectureprimary
Lessons learned#
- Worked
Deriving the OpenAPI document from the same schemas the handlers use meant the docs could not drift from behavior.
- Decision
Cursor pagination was used instead of page numbers because work orders are inserted constantly and page numbers shifted under users.
Try it#
git clone https://git.example.internal/developer-experience/rest-work-orders-node.git
cd rest-work-orders-node
pnpm install
pnpm dev # http://localhost:4000
pnpm test:contract # shared acceptance suiteCommands come from the owner’s README. Credentials are never stored here.
