Part 3: Building REST APIs with Express.js and TypeScript

From Zero to Production-Ready API

Three years ago, I started my first Express.js API project. I wrote everything in one server.js file—routes, business logic, database queries, all mixed together. By day 3, the file was 800 lines. By week 2, I couldn't find anything. Adding a feature meant scrolling through spaghetti code.

Today, my microservices use a structured architecture: separate layers for routes, controllers, services, and repositories. Each component has one responsibility. Adding features takes minutes instead of hours.

This article shows you how to build production-ready REST APIs using the structure I wish I'd known from day one.

Project Setup

Initialize TypeScript Project

# Create project directory
mkdir user-service
cd user-service

# Initialize package.json
npm init -y

# Install dependencies
npm install express
npm install cors helmet morgan
npm install pg              # PostgreSQL client
npm install dotenv          # Environment variables

# Install TypeScript dependencies
npm install -D typescript @types/node @types/express
npm install -D @types/cors @types/morgan
npm install -D ts-node nodemon
npm install -D @types/pg

# Initialize TypeScript
npx tsc --init

TypeScript Configuration

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "moduleResolution": "node",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Project Structure

user-service/
├── src/
│   ├── config/
│   │   ├── database.ts
│   │   └── environment.ts
│   ├── controllers/
│   │   └── user-controller.ts
│   ├── services/
│   │   └── user-service.ts
│   ├── repositories/
│   │   └── user-repository.ts
│   ├── routes/
│   │   ├── index.ts
│   │   └── user-routes.ts
│   ├── middleware/
│   │   ├── error-handler.ts
│   │   ├── logger.ts
│   │   └── validator.ts
│   ├── types/
│   │   ├── user.ts
│   │   └── api-response.ts
│   ├── utils/
│   │   └── response-formatter.ts
│   ├── app.ts
│   └── server.ts
├── .env
├── .env.example
├── .gitignore
├── package.json
└── tsconfig.json

Package.json Scripts

{
  "scripts": {
    "dev": "nodemon src/server.ts",
    "build": "tsc",
    "start": "node dist/server.js",
    "lint": "eslint src --ext .ts",
    "test": "jest"
  }
}

Environment Configuration

// src/config/environment.ts
import dotenv from 'dotenv';

dotenv.config();

interface EnvironmentConfig {
  port: number;
  nodeEnv: string;
  database: {
    host: string;
    port: number;
    name: string;
    user: string;
    password: string;
  };
  jwt: {
    secret: string;
    expiresIn: string;
  };
}

export const config: EnvironmentConfig = {
  port: parseInt(process.env.PORT || '4000'),
  nodeEnv: process.env.NODE_ENV || 'development',
  database: {
    host: process.env.DB_HOST || 'localhost',
    port: parseInt(process.env.DB_PORT || '5432'),
    name: process.env.DB_NAME || 'userdb',
    user: process.env.DB_USER || 'postgres',
    password: process.env.DB_PASSWORD || 'password',
  },
  jwt: {
    secret: process.env.JWT_SECRET || 'your-secret-key',
    expiresIn: process.env.JWT_EXPIRES_IN || '24h',
  },
};

# .env.example
PORT=4000
NODE_ENV=development

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=userdb
DB_USER=postgres
DB_PASSWORD=password

# JWT
JWT_SECRET=your-secret-key-change-in-production
JWT_EXPIRES_IN=24h

Database Configuration

// src/config/database.ts
import { Pool } from 'pg';
import { config } from './environment';

export class Database {
  private static instance: Pool;

  static getInstance(): Pool {
    if (!this.instance) {
      this.instance = new Pool({
        host: config.database.host,
        port: config.database.port,
        database: config.database.name,
        user: config.database.user,
        password: config.database.password,
        max: 20, // Maximum pool size
        idleTimeoutMillis: 30000,
        connectionTimeoutMillis: 2000,
      });

      // Connection event handlers
      this.instance.on('connect', () => {
        console.log('✅ Database connected');
      });

      this.instance.on('error', (err) => {
        console.error('❌ Database error:', err);
      });
    }

    return this.instance;
  }

  static async testConnection(): Promise<boolean> {
    try {
      const pool = this.getInstance();
      await pool.query('SELECT NOW()');
      console.log('✅ Database connection test successful');
      return true;
    } catch (error) {
      console.error('❌ Database connection test failed:', error);
      return false;
    }
  }

  static async close(): Promise<void> {
    if (this.instance) {
      await this.instance.end();
      console.log('Database connection pool closed');
    }
  }
}

Type Definitions

// src/types/user.ts
export interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
  updatedAt: Date;
}

export interface CreateUserDto {
  email: string;
  password: string;
  name: string;
}

export interface UpdateUserDto {
  email?: string;
  name?: string;
}

// src/types/api-response.ts
export interface ApiResponse<T = any> {
  success: boolean;
  data?: T;
  error?: string;
  errors?: string[];
  message?: string;
  meta?: Record<string, any>;
}

Repository Layer (Data Access)

// src/repositories/user-repository.ts
import { Pool } from 'pg';
import { User, CreateUserDto, UpdateUserDto } from '../types/user';

export class UserRepository {
  constructor(private readonly db: Pool) {}

  async findAll(): Promise<User[]> {
    const result = await this.db.query(
      'SELECT id, email, name, created_at, updated_at FROM users ORDER BY created_at DESC'
    );
    return result.rows.map(this.mapToUser);
  }

  async findById(id: string): Promise<User | null> {
    const result = await this.db.query(
      'SELECT id, email, name, created_at, updated_at FROM users WHERE id = $1',
      [id]
    );
    
    if (result.rows.length === 0) {
      return null;
    }
    
    return this.mapToUser(result.rows[0]);
  }

  async findByEmail(email: string): Promise<User | null> {
    const result = await this.db.query(
      'SELECT id, email, name, created_at, updated_at FROM users WHERE email = $1',
      [email]
    );
    
    if (result.rows.length === 0) {
      return null;
    }
    
    return this.mapToUser(result.rows[0]);
  }

  async create(userData: CreateUserDto): Promise<User> {
    const result = await this.db.query(
      `INSERT INTO users (id, email, password, name, created_at, updated_at)
       VALUES ($1, $2, $3, $4, NOW(), NOW())
       RETURNING id, email, name, created_at, updated_at`,
      [
        this.generateId(),
        userData.email,
        userData.password, // Should be hashed before this
        userData.name,
      ]
    );
    
    return this.mapToUser(result.rows[0]);
  }

  async update(id: string, updates: UpdateUserDto): Promise<User | null> {
    const fields: string[] = [];
    const values: any[] = [];
    let paramIndex = 1;

    if (updates.email) {
      fields.push(`email = $${paramIndex++}`);
      values.push(updates.email);
    }

    if (updates.name) {
      fields.push(`name = $${paramIndex++}`);
      values.push(updates.name);
    }

    if (fields.length === 0) {
      return this.findById(id);
    }

    fields.push(`updated_at = NOW()`);
    values.push(id);

    const result = await this.db.query(
      `UPDATE users
       SET ${fields.join(', ')}
       WHERE id = $${paramIndex}
       RETURNING id, email, name, created_at, updated_at`,
      values
    );

    if (result.rows.length === 0) {
      return null;
    }

    return this.mapToUser(result.rows[0]);
  }

  async delete(id: string): Promise<boolean> {
    const result = await this.db.query('DELETE FROM users WHERE id = $1', [id]);
    return result.rowCount > 0;
  }

  async count(): Promise<number> {
    const result = await this.db.query('SELECT COUNT(*) FROM users');
    return parseInt(result.rows[0].count);
  }

  private mapToUser(row: any): User {
    return {
      id: row.id,
      email: row.email,
      name: row.name,
      createdAt: row.created_at,
      updatedAt: row.updated_at,
    };
  }

  private generateId(): string {
    return `user_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
  }
}

Service Layer (Business Logic)

// src/services/user-service.ts
import { User, CreateUserDto, UpdateUserDto } from '../types/user';
import { UserRepository } from '../repositories/user-repository';
import bcrypt from 'bcrypt';

export class UserService {
  constructor(private readonly userRepository: UserRepository) {}

  async getAllUsers(): Promise<User[]> {
    return this.userRepository.findAll();
  }

  async getUserById(id: string): Promise<User | null> {
    return this.userRepository.findById(id);
  }

  async getUserByEmail(email: string): Promise<User | null> {
    return this.userRepository.findByEmail(email);
  }

  async createUser(userData: CreateUserDto): Promise<User> {
    // Business logic: Check if email exists
    const existingUser = await this.userRepository.findByEmail(userData.email);
    if (existingUser) {
      throw new Error('Email already registered');
    }

    // Business logic: Validate email format
    if (!this.isValidEmail(userData.email)) {
      throw new Error('Invalid email format');
    }

    // Business logic: Validate password strength
    if (!this.isStrongPassword(userData.password)) {
      throw new Error('Password must be at least 8 characters with uppercase, lowercase, and number');
    }

    // Hash password before storing
    const hashedPassword = await bcrypt.hash(userData.password, 10);

    return this.userRepository.create({
      ...userData,
      password: hashedPassword,
    });
  }

  async updateUser(id: string, updates: UpdateUserDto): Promise<User | null> {
    // Check if user exists
    const user = await this.userRepository.findById(id);
    if (!user) {
      return null;
    }

    // Validate email if being updated
    if (updates.email) {
      if (!this.isValidEmail(updates.email)) {
        throw new Error('Invalid email format');
      }

      // Check if new email is already taken
      const existingUser = await this.userRepository.findByEmail(updates.email);
      if (existingUser && existingUser.id !== id) {
        throw new Error('Email already in use');
      }
    }

    return this.userRepository.update(id, updates);
  }

  async deleteUser(id: string): Promise<boolean> {
    const user = await this.userRepository.findById(id);
    if (!user) {
      return false;
    }

    return this.userRepository.delete(id);
  }

  async getUserCount(): Promise<number> {
    return this.userRepository.count();
  }

  private isValidEmail(email: string): boolean {
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return emailRegex.test(email);
  }

  private isStrongPassword(password: string): boolean {
    // At least 8 characters, 1 uppercase, 1 lowercase, 1 number
    const hasLength = password.length >= 8;
    const hasUppercase = /[A-Z]/.test(password);
    const hasLowercase = /[a-z]/.test(password);
    const hasNumber = /\d/.test(password);
    
    return hasLength && hasUppercase && hasLowercase && hasNumber;
  }
}

Controller Layer (Request Handling)

// src/controllers/user-controller.ts
import { Request, Response } from 'express';
import { UserService } from '../services/user-service';
import { ResponseFormatter } from '../utils/response-formatter';

export class UserController {
  constructor(private readonly userService: UserService) {}

  async getAllUsers(req: Request, res: Response): Promise<void> {
    try {
      const users = await this.userService.getAllUsers();
      
      res.json(ResponseFormatter.success(users, undefined, {
        count: users.length,
      }));
    } catch (error) {
      res.status(500).json(
        ResponseFormatter.error('Failed to fetch users')
      );
    }
  }

  async getUserById(req: Request, res: Response): Promise<void> {
    try {
      const { id } = req.params;
      const user = await this.userService.getUserById(id);
      
      if (!user) {
        res.status(404).json(
          ResponseFormatter.error('User not found')
        );
        return;
      }
      
      res.json(ResponseFormatter.success(user));
    } catch (error) {
      res.status(500).json(
        ResponseFormatter.error('Failed to fetch user')
      );
    }
  }

  async createUser(req: Request, res: Response): Promise<void> {
    try {
      const { email, password, name } = req.body;
      
      // Validation
      if (!email || !password || !name) {
        res.status(400).json(
          ResponseFormatter.error('Email, password, and name are required')
        );
        return;
      }
      
      const user = await this.userService.createUser({
        email,
        password,
        name,
      });
      
      res.status(201).json(
        ResponseFormatter.success(user, 'User created successfully')
      );
    } catch (error) {
      if (error instanceof Error) {
        res.status(400).json(
          ResponseFormatter.error(error.message)
        );
      } else {
        res.status(500).json(
          ResponseFormatter.error('Failed to create user')
        );
      }
    }
  }

  async updateUser(req: Request, res: Response): Promise<void> {
    try {
      const { id } = req.params;
      const updates = req.body;
      
      const user = await this.userService.updateUser(id, updates);
      
      if (!user) {
        res.status(404).json(
          ResponseFormatter.error('User not found')
        );
        return;
      }
      
      res.json(
        ResponseFormatter.success(user, 'User updated successfully')
      );
    } catch (error) {
      if (error instanceof Error) {
        res.status(400).json(
          ResponseFormatter.error(error.message)
        );
      } else {
        res.status(500).json(
          ResponseFormatter.error('Failed to update user')
        );
      }
    }
  }

  async deleteUser(req: Request, res: Response): Promise<void> {
    try {
      const { id } = req.params;
      const deleted = await this.userService.deleteUser(id);
      
      if (!deleted) {
        res.status(404).json(
          ResponseFormatter.error('User not found')
        );
        return;
      }
      
      res.status(204).send();
    } catch (error) {
      res.status(500).json(
        ResponseFormatter.error('Failed to delete user')
      );
    }
  }
}

Routes

// src/routes/user-routes.ts
import { Router } from 'express';
import { UserController } from '../controllers/user-controller';

export class UserRoutes {
  static setup(controller: UserController): Router {
    const router = Router();

    router.get('/', controller.getAllUsers.bind(controller));
    router.get('/:id', controller.getUserById.bind(controller));
    router.post('/', controller.createUser.bind(controller));
    router.patch('/:id', controller.updateUser.bind(controller));
    router.delete('/:id', controller.deleteUser.bind(controller));

    return router;
  }
}

// src/routes/index.ts
import { Router } from 'express';
import { UserRoutes } from './user-routes';
import { Database } from '../config/database';
import { UserRepository } from '../repositories/user-repository';
import { UserService } from '../services/user-service';
import { UserController } from '../controllers/user-controller';

export class ApiRoutes {
  static setup(): Router {
    const router = Router();

    // Dependency injection
    const db = Database.getInstance();
    const userRepository = new UserRepository(db);
    const userService = new UserService(userRepository);
    const userController = new UserController(userService);

    // Mount routes
    router.use('/users', UserRoutes.setup(userController));

    // Health check
    router.get('/health', (req, res) => {
      res.json({
        success: true,
        data: {
          status: 'healthy',
          timestamp: new Date().toISOString(),
        },
      });
    });

    return router;
  }
}

Middleware

// src/middleware/error-handler.ts
import { Request, Response, NextFunction } from 'express';
import { ResponseFormatter } from '../utils/response-formatter';

export class ErrorHandler {
  static handle(err: Error, req: Request, res: Response, next: NextFunction) {
    console.error('Error:', err);

    // Database errors
    if (err.message.includes('ECONNREFUSED')) {
      return res.status(503).json(
        ResponseFormatter.error('Database temporarily unavailable')
      );
    }

    // Validation errors
    if (err.name === 'ValidationError') {
      return res.status(400).json(
        ResponseFormatter.error(err.message)
      );
    }

    // Default error
    return res.status(500).json(
      ResponseFormatter.error('Internal server error')
    );
  }
}

// src/middleware/logger.ts
import { Request, Response, NextFunction } from 'express';

export class LoggerMiddleware {
  static log(req: Request, res: Response, next: NextFunction) {
    const start = Date.now();

    res.on('finish', () => {
      const duration = Date.now() - start;
      console.log(
        `${req.method} ${req.path} ${res.statusCode} ${duration}ms`
      );
    });

    next();
  }
}

Utility Functions

// src/utils/response-formatter.ts
import { ApiResponse } from '../types/api-response';

export class ResponseFormatter {
  static success<T>(
    data: T,
    message?: string,
    meta?: Record<string, any>
  ): ApiResponse<T> {
    return {
      success: true,
      data,
      ...(message && { message }),
      ...(meta && { meta }),
    };
  }

  static error(error: string, errors?: string[]): ApiResponse {
    return {
      success: false,
      error,
      ...(errors && { errors }),
    };
  }
}

Application Setup

// src/app.ts
import express, { Application } from 'express';
import cors from 'cors';
import helmet from 'helmet';
import morgan from 'morgan';
import { ApiRoutes } from './routes';
import { ErrorHandler } from './middleware/error-handler';
import { LoggerMiddleware } from './middleware/logger';

export class App {
  private app: Application;

  constructor() {
    this.app = express();
    this.setupMiddleware();
    this.setupRoutes();
    this.setupErrorHandling();
  }

  private setupMiddleware(): void {
    // Security
    this.app.use(helmet());
    
    // CORS
    this.app.use(cors({
      origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',
      credentials: true,
    }));

    // Body parsing
    this.app.use(express.json());
    this.app.use(express.urlencoded({ extended: true }));

    // Logging
    if (process.env.NODE_ENV === 'development') {
      this.app.use(morgan('dev'));
    }
    this.app.use(LoggerMiddleware.log);
  }

  private setupRoutes(): void {
    this.app.use('/api/v1', ApiRoutes.setup());
  }

  private setupErrorHandling(): void {
    this.app.use(ErrorHandler.handle);
  }

  getApp(): Application {
    return this.app;
  }
}

// src/server.ts
import { App } from './app';
import { config } from './config/environment';
import { Database } from './config/database';

async function startServer() {
  try {
    // Test database connection
    const dbConnected = await Database.testConnection();
    if (!dbConnected) {
      console.error('Failed to connect to database');
      process.exit(1);
    }

    // Start Express server
    const app = new App().getApp();
    
    const server = app.listen(config.port, () => {
      console.log(`🚀 Server running on port ${config.port}`);
      console.log(`📝 Environment: ${config.nodeEnv}`);
      console.log(`🔗 API: http://localhost:${config.port}/api/v1`);
    });

    // Graceful shutdown
    process.on('SIGTERM', async () => {
      console.log('SIGTERM received, shutting down gracefully');
      server.close(async () => {
        await Database.close();
        process.exit(0);
      });
    });
  } catch (error) {
    console.error('Failed to start server:', error);
    process.exit(1);
  }
}

startServer();

Testing the API

# Start development server
npm run dev

# Create user
curl -X POST http://localhost:4000/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123",
    "name": "John Doe"
  }'

# Get all users
curl http://localhost:4000/api/v1/users

# Get specific user
curl http://localhost:4000/api/v1/users/user_123

# Update user
curl -X PATCH http://localhost:4000/api/v1/users/user_123 \
  -H "Content-Type: application/json" \
  -d '{"name": "John Updated"}'

# Delete user
curl -X DELETE http://localhost:4000/api/v1/users/user_123

# Health check
curl http://localhost:4000/api/v1/health

Key Takeaways

1. Layered architecture: Routes → Controllers → Services → Repositories

2. TypeScript for type safety and better developer experience

3. Dependency injection makes testing easier

4. Consistent error handling across all endpoints

5. Environment configuration separates dev/staging/prod settings

6. Connection pooling for efficient database access

7. Graceful shutdown prevents data loss

8. Structured logging for debugging

9. Security headers (helmet) by default

10. Health checks for monitoring

Next in series: Authentication and Authorization—securing your REST API with JWT and role-based access control.

---

A well-structured codebase scales better than clever code. Start with good architecture, and maintenance becomes easier.