How to Build a Production-Ready REST API with Node.js and TypeScript

Building a REST API with Node.js is straightforward. Building one that's maintainable at scale — with proper typing, input validation, authentication, error handling, and testability — takes significantly more thought. TypeScript eliminates whole categories of bugs that plague JavaScript APIs. Combined with modern tooling like Zod for runtime validation, Prisma for database access, and structured error handling, you get an API codebase that a team can confidently work in for years.

This guide walks through building a production-ready REST API from scratch. You can test the endpoints we build with our API Tester and format response payloads with the JSON Formatter.

Project Setup

mkdir my-api && cd my-api
npm init -y

# TypeScript + build tools
npm install -D typescript ts-node nodemon @types/node
npm install -D @types/express

# Core dependencies
npm install express
npm install zod           # Runtime validation
npm install prisma @prisma/client  # Database ORM
npm install jsonwebtoken @types/jsonwebtoken  # JWT auth
npm install bcryptjs @types/bcryptjs  # Password hashing
npm install helmet cors   # Security middleware
npm install express-rate-limit  # Rate limiting
npm install winston       # Structured logging
npm install -D jest @types/jest ts-jest supertest @types/supertest  # Testing

TypeScript Configuration

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

Project Structure

src/
├── app.ts              # Express app setup (no server.listen)
├── server.ts           # Entry point (server.listen)
├── config/
│   └── env.ts          # Validated environment variables
├── middleware/
│   ├── auth.ts         # JWT verification middleware
│   ├── errorHandler.ts # Central error handler
│   └── validate.ts     # Zod validation middleware
├── modules/
│   └── users/
│       ├── users.router.ts
│       ├── users.controller.ts
│       ├── users.service.ts
│       └── users.schema.ts
├── lib/
│   ├── db.ts           # Prisma client singleton
│   ├── logger.ts       # Winston logger
│   └── errors.ts       # Custom error classes
└── types/
    └── express.d.ts    # Express type augmentation

Environment Validation with Zod

Never trust process.env — validate and type it at startup:

// src/config/env.ts
import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().int().positive().default(3000),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 characters'),
  JWT_EXPIRES_IN: z.string().default('7d'),
  BCRYPT_ROUNDS: z.coerce.number().int().min(10).max(14).default(12),
  RATE_LIMIT_WINDOW_MS: z.coerce.number().default(15 * 60 * 1000), // 15 min
  RATE_LIMIT_MAX: z.coerce.number().default(100),
  CORS_ORIGIN: z.string().default('*'),
});

// Parse and validate — throws at startup if invalid
const parsed = envSchema.safeParse(process.env);

if (!parsed.success) {
  console.error('❌ Invalid environment variables:');
  console.error(parsed.error.flatten().fieldErrors);
  process.exit(1);
}

export const env = parsed.data;
export type Env = z.infer<typeof envSchema>;

Custom Error Classes

// src/lib/errors.ts
export class AppError extends Error {
  constructor(
    public message: string,
    public statusCode: number,
    public code: string,
    public details?: unknown
  ) {
    super(message);
    this.name = 'AppError';
    Error.captureStackTrace(this, this.constructor);
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string, id?: string | number) {
    super(
      id ? `${resource} with id '${id}' not found` : `${resource} not found`,
      404,
      'NOT_FOUND'
    );
  }
}

export class UnauthorizedError extends AppError {
  constructor(message = 'Authentication required') {
    super(message, 401, 'UNAUTHORIZED');
  }
}

export class ForbiddenError extends AppError {
  constructor(message = 'Insufficient permissions') {
    super(message, 403, 'FORBIDDEN');
  }
}

export class ConflictError extends AppError {
  constructor(message: string) {
    super(message, 409, 'CONFLICT');
  }
}

export class ValidationError extends AppError {
  constructor(details: unknown) {
    super('Validation failed', 422, 'VALIDATION_ERROR', details);
  }
}

Zod Validation Middleware

// src/middleware/validate.ts
import { Request, Response, NextFunction } from 'express';
import { AnyZodObject, ZodError, z } from 'zod';
import { ValidationError } from '../lib/errors';

type RequestSchema = {
  body?: AnyZodObject;
  query?: AnyZodObject;
  params?: AnyZodObject;
};

export function validate(schema: RequestSchema) {
  return async (req: Request, res: Response, next: NextFunction) => {
    try {
      if (schema.body) req.body = await schema.body.parseAsync(req.body);
      if (schema.query) req.query = await schema.query.parseAsync(req.query);
      if (schema.params) req.params = await schema.params.parseAsync(req.params);
      next();
    } catch (err) {
      if (err instanceof ZodError) {
        next(new ValidationError(err.flatten().fieldErrors));
      } else {
        next(err);
      }
    }
  };
}

JWT Authentication Middleware

// src/types/express.d.ts — augment Express Request
import { User } from '@prisma/client';
declare global {
  namespace Express {
    interface Request {
      user?: Omit<User, 'password'>;
    &#125;
  &#125;
&#125;

// src/middleware/auth.ts
import &#123; Request, Response, NextFunction &#125; from 'express';
import jwt from 'jsonwebtoken';
import &#123; env &#125; from '../config/env';
import &#123; UnauthorizedError &#125; from '../lib/errors';
import &#123; db &#125; from '../lib/db';

interface JwtPayload &#123;
  sub: string; // user id
  iat: number;
  exp: number;
&#125;

export async function requireAuth(req: Request, res: Response, next: NextFunction) &#123;
  try &#123;
    const authHeader = req.headers.authorization;
    if (!authHeader?.startsWith('Bearer ')) &#123;
      throw new UnauthorizedError('Missing or invalid authorization header');
    &#125;

    const token = authHeader.slice(7);

    let payload: JwtPayload;
    try &#123;
      payload = jwt.verify(token, env.JWT_SECRET) as JwtPayload;
    &#125; catch &#123;
      throw new UnauthorizedError('Invalid or expired token');
    &#125;

    const user = await db.user.findUnique(&#123;
      where: &#123; id: payload.sub &#125;,
      omit: &#123; password: true &#125;,
    &#125;);

    if (!user) throw new UnauthorizedError('User not found');

    req.user = user;
    next();
  &#125; catch (err) &#123;
    next(err);
  &#125;
&#125;

// Optional auth — attaches user if token present but doesn't require it
export async function optionalAuth(req: Request, res: Response, next: NextFunction) &#123;
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('Bearer ')) return next();

  try &#123;
    const token = authHeader.slice(7);
    const payload = jwt.verify(token, env.JWT_SECRET) as JwtPayload;
    const user = await db.user.findUnique(&#123;
      where: &#123; id: payload.sub &#125;,
      omit: &#123; password: true &#125;,
    &#125;);
    if (user) req.user = user;
  &#125; catch &#123;
    // Ignore invalid tokens for optional auth
  &#125;
  next();
&#125;

Module Structure: Users Example

// src/modules/users/users.schema.ts
import { z } from 'zod';

export const createUserSchema = {
  body: z.object({
    email: z.string().email(),
    password: z.string().min(8).max(100),
    name: z.string().min(1).max(100).trim(),
  }),
};

export const loginSchema = {
  body: z.object({
    email: z.string().email(),
    password: z.string(),
  }),
};

export const updateUserSchema = {
  params: z.object({ id: z.string().cuid() }),
  body: z.object({
    name: z.string().min(1).max(100).trim().optional(),
    email: z.string().email().optional(),
  }).strict(), // Reject unknown fields
};

export type CreateUserInput = z.infer<typeof createUserSchema.body>;
export type LoginInput = z.infer<typeof loginSchema.body>;
export type UpdateUserInput = z.infer<typeof updateUserSchema.body>;

// src/modules/users/users.service.ts
import bcrypt from 'bcryptjs';
import jwt from 'jsonwebtoken';
import { db } from '../../lib/db';
import { env } from '../../config/env';
import { NotFoundError, ConflictError, UnauthorizedError } from '../../lib/errors';
import type { CreateUserInput, LoginInput, UpdateUserInput } from './users.schema';

export async function createUser(input: CreateUserInput) {
  const existing = await db.user.findUnique({ where: { email: input.email } });
  if (existing) throw new ConflictError('Email already registered');

  const hashedPassword = await bcrypt.hash(input.password, env.BCRYPT_ROUNDS);

  const user = await db.user.create({
    data: { ...input, password: hashedPassword },
    omit: { password: true },
  });

  return user;
}

export async function login(input: LoginInput) {
  const user = await db.user.findUnique({ where: { email: input.email } });
  if (!user) throw new UnauthorizedError('Invalid credentials');

  const valid = await bcrypt.compare(input.password, user.password);
  if (!valid) throw new UnauthorizedError('Invalid credentials');

  const token = jwt.sign({ sub: user.id }, env.JWT_SECRET, {
    expiresIn: env.JWT_EXPIRES_IN,
  });

  const { password: _, ...userWithoutPassword } = user;
  return { user: userWithoutPassword, token };
}

export async function getUserById(id: string) {
  const user = await db.user.findUnique({
    where: { id },
    omit: { password: true },
  });
  if (!user) throw new NotFoundError('User', id);
  return user;
}

export async function updateUser(id: string, input: UpdateUserInput) {
  await getUserById(id); // Ensures user exists, throws 404 if not
  return db.user.update({
    where: { id },
    data: input,
    omit: { password: true },
  });
}

export async function deleteUser(id: string) {
  await getUserById(id);
  await db.user.delete({ where: { id } });
}

// src/modules/users/users.controller.ts
import { Request, Response } from 'express';
import * as usersService from './users.service';

export async function createUser(req: Request, res: Response) {
  const user = await usersService.createUser(req.body);
  res.status(201).json({ data: user });
}

export async function login(req: Request, res: Response) {
  const result = await usersService.login(req.body);
  res.json({ data: result });
}

export async function getMe(req: Request, res: Response) {
  res.json({ data: req.user });
}

export async function getUserById(req: Request, res: Response) {
  const user = await usersService.getUserById(req.params.id!);
  res.json({ data: user });
}

export async function updateUser(req: Request, res: Response) {
  const user = await usersService.updateUser(req.params.id!, req.body);
  res.json({ data: user });
}

export async function deleteUser(req: Request, res: Response) {
  await usersService.deleteUser(req.params.id!);
  res.status(204).send();
}

// src/modules/users/users.router.ts
import { Router } from 'express';
import { validate } from '../../middleware/validate';
import { requireAuth } from '../../middleware/auth';
import * as usersController from './users.controller';
import { createUserSchema, loginSchema, updateUserSchema } from './users.schema';

const router = Router();

// Public routes
router.post('/register', validate(createUserSchema), usersController.createUser);
router.post('/login', validate(loginSchema), usersController.login);

// Protected routes
router.get('/me', requireAuth, usersController.getMe);
router.get('/:id', requireAuth, usersController.getUserById);
router.patch('/:id', requireAuth, validate(updateUserSchema), usersController.updateUser);
router.delete('/:id', requireAuth, usersController.deleteUser);

export { router as usersRouter };

Central Error Handler

// src/middleware/errorHandler.ts
import { Request, Response, NextFunction } from 'express';
import { AppError } from '../lib/errors';
import { logger } from '../lib/logger';
import { env } from '../config/env';

export function errorHandler(
  err: Error,
  req: Request,
  res: Response,
  next: NextFunction
) {
  if (err instanceof AppError) {
    // Known, intentional errors
    if (err.statusCode >= 500) {
      logger.error({ err, req: { method: req.method, url: req.url } });
    }

    res.status(err.statusCode).json({
      error: {
        code: err.code,
        message: err.message,
        ...(err.details ? { details: err.details } : {}),
        ...(env.NODE_ENV === 'development' ? { stack: err.stack } : {}),
      },
    });
  } else {
    // Unknown errors — log everything, expose little
    logger.error({ err, req: { method: req.method, url: req.url } });

    res.status(500).json({
      error: {
        code: 'INTERNAL_SERVER_ERROR',
        message: 'An unexpected error occurred',
        ...(env.NODE_ENV === 'development' ? { originalError: err.message } : {}),
      },
    });
  }
}

Async Handler Wrapper

Express 4 doesn't catch async errors automatically. Wrap every async route handler:

// src/lib/asyncHandler.ts
import { Request, Response, NextFunction, RequestHandler } from 'express';

type AsyncRequestHandler = (req: Request, res: Response, next: NextFunction) => Promise<void>;

export function asyncHandler(fn: AsyncRequestHandler): RequestHandler &#123;
  return (req, res, next) => &#123;
    fn(req, res, next).catch(next);
  &#125;;
&#125;

// Usage in router:
router.get('/:id', requireAuth, asyncHandler(usersController.getUserById));

// Note: Express 5 (currently in beta) handles async errors natively,
// making asyncHandler unnecessary. Consider using express@next.

App Assembly

// src/app.ts
import express from 'express';
import helmet from 'helmet';
import cors from 'cors';
import rateLimit from 'express-rate-limit';
import { env } from './config/env';
import { errorHandler } from './middleware/errorHandler';
import { usersRouter } from './modules/users/users.router';
import { logger } from './lib/logger';

export const app = express();

// Security middleware
app.use(helmet());
app.use(cors({ origin: env.CORS_ORIGIN, credentials: true }));
app.use(rateLimit({
  windowMs: env.RATE_LIMIT_WINDOW_MS,
  max: env.RATE_LIMIT_MAX,
  standardHeaders: true,
  legacyHeaders: false,
}));

// Body parsing
app.use(express.json({ limit: '10mb' }));
app.use(express.urlencoded({ extended: true }));

// Request logging
app.use((req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    logger.info({
      method: req.method,
      url: req.url,
      status: res.statusCode,
      duration: Date.now() - start,
    });
  });
  next();
});

// Routes
app.get('/health', (req, res) => res.json({ status: 'ok', uptime: process.uptime() }));
app.use('/api/v1/users', usersRouter);

// 404 handler
app.use((req, res) => {
  res.status(404).json({ error: { code: 'NOT_FOUND', message: 'Route not found' } });
});

// Central error handler (must be last)
app.use(errorHandler);

Testing with Supertest

// src/modules/users/__tests__/users.test.ts
import request from 'supertest';
import { app } from '../../../app';
import { db } from '../../../lib/db';

beforeEach(async () => {
  // Clean database before each test (use transactions for speed)
  await db.user.deleteMany();
});

afterAll(async () => {
  await db.$disconnect();
});

describe('POST /api/v1/users/register', () => {
  it('creates a new user', async () => {
    const res = await request(app)
      .post('/api/v1/users/register')
      .send({ email: '[e-mail]', password: 'Password123!', name: 'Test User' });

    expect(res.status).toBe(201);
    expect(res.body.data).toMatchObject({
      email: '[e-mail]',
      name: 'Test User',
    });
    expect(res.body.data.password).toBeUndefined(); // Never return password
  });

  it('returns 409 for duplicate email', async () => {
    const user = { email: '[e-mail]', password: 'Password123!', name: 'Test' };
    await request(app).post('/api/v1/users/register').send(user);
    const res = await request(app).post('/api/v1/users/register').send(user);

    expect(res.status).toBe(409);
    expect(res.body.error.code).toBe('CONFLICT');
  });

  it('validates email format', async () => {
    const res = await request(app)
      .post('/api/v1/users/register')
      .send({ email: 'notanemail', password: 'Password123!', name: 'Test' });

    expect(res.status).toBe(422);
    expect(res.body.error.code).toBe('VALIDATION_ERROR');
  });
});

Key Takeaways

• Validate environment variables at startup with Zod — don't discover missing env vars in production
• Use custom error classes with status codes and error codes for consistent API responses
• Keep controllers thin: just call the service and send the response
• Always wrap async route handlers to ensure errors propagate to the central error handler
• Never return password fields — use Prisma's omit or explicit select
• Test the HTTP layer with Supertest, not just unit tests on services

For more on securing your API, see our guide on securing Node.js APIs in 2026 and how JWT tokens work.

Free Developer Tools

If you found this article helpful, check out DevToolkit — 40+ free browser-based developer tools with no signup required.

Popular tools: JSON Formatter · Regex Tester · JWT Decoder · Base64 Encoder

🛒 Get the DevToolkit Starter Kit on Gumroad — source code, deployment guide, and customization templates.