Tutorial |

Building a Production-Ready REST API with Node.js and Express

Tue, 10 Dec 2024 00:00:00 +0000

Building a REST API seems straightforward until you need to handle authentication, validation, error handling, and documentation. This guide covers best practices for production-ready APIs.

Project Setup

Start with a solid foundation:

mkdir my-api && cd my-api
npm init -y
npm install express dotenv cors helmet compression
npm install -D typescript @types/node @types/express ts-node-dev

Create tsconfig.json:

{
 "compilerOptions": {
 "target": "ES2020",
 "module": "commonjs",
 "lib": ["ES2020"],
 "outDir": "./dist",
 "rootDir": "./src",
 "strict": true,
 "esModuleInterop": true,
 "skipLibCheck": true
 }
}

Folder Structure

Organize your code for maintainability:

src/
├── config/ # Configuration files
├── controllers/ # Route controllers
├── middleware/ # Custom middleware
├── models/ # Database models
├── routes/ # API routes
├── services/ # Business logic
├── utils/ # Helper functions
├── validators/ # Input validation
└── app.ts # App setup

Database Integration

Using Prisma for type-safe database access:

// prisma/schema.prisma
model User {
 id String @id @default(uuid())
 email String @unique
 name String
 password String
 createdAt DateTime @default(now())
 updatedAt DateTime @updatedAt
}

// src/config/database.ts
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient({
 log: process.env.NODE_ENV === 'development' ? ['query'] : []
})

export default prisma

Authentication & Authorization

Implement JWT-based authentication:

// src/middleware/auth.ts
import jwt from 'jsonwebtoken'
import { Request, Response, NextFunction } from 'express'

interface JWTPayload {
 userId: string
 email: string
}

export const authenticate = async (
 req: Request,
 res: Response,
 next: NextFunction
) => {
 try {
 const token = req.headers.authorization?.split(' ')[1]

 if (!token) {
 return res.status(401).json({ error: 'Authentication required' })
 }

 const payload = jwt.verify(
 token,
 process.env.JWT_SECRET!
 ) as JWTPayload

 req.user = payload
 next()
 } catch (error) {
 res.status(401).json({ error: 'Invalid or expired token' })
 }
}

Error Handling

Centralized error handling:

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

class AppError extends Error {
 statusCode: number
 isOperational: boolean

 constructor(message: string, statusCode: number) {
 super(message)
 this.statusCode = statusCode
 this.isOperational = true
 Error.captureStackTrace(this, this.constructor)
 }
}

export const errorHandler = (
 err: Error,
 req: Request,
 res: Response,
 next: NextFunction
) => {
 if (err instanceof AppError) {
 return res.status(err.statusCode).json({
 status: 'error',
 message: err.message
 })
 }

 // Log unexpected errors
 console.error('Unexpected error:', err)

 res.status(500).json({
 status: 'error',
 message: 'Internal server error'
 })
}

export { AppError }

Validation

Use Zod for runtime validation:

// src/validators/userValidator.ts
import { z } from 'zod'

export const createUserSchema = z.object({
 body: z.object({
 email: z.string().email('Invalid email address'),
 name: z.string().min(2, 'Name must be at least 2 characters'),
 password: z.string().min(8, 'Password must be at least 8 characters')
 })
})

export const validate = (schema: any) => {
 return async (req: Request, res: Response, next: NextFunction) => {
 try {
 await schema.parseAsync({
 body: req.body,
 query: req.query,
 params: req.params
 })
 next()
 } catch (error) {
 if (error instanceof z.ZodError) {
 return res.status(400).json({
 status: 'error',
 errors: error.errors
 })
 }
 next(error)
 }
 }
}

API Documentation

Auto-generate docs with Swagger:

// src/config/swagger.ts
import swaggerJsdoc from 'swagger-jsdoc'

const options = {
 definition: {
 openapi: '3.0.0',
 info: {
 title: 'My API',
 version: '1.0.0',
 description: 'API documentation'
 },
 servers: [
 {
 url: 'http://localhost:3000',
 description: 'Development server'
 }
 ]
 },
 apis: ['./src/routes/*.ts']
}

export const swaggerSpec = swaggerJsdoc(options)

Document endpoints in route files:

/**
 * @openapi
 * /api/users:
 * post:
 * summary: Create a new user
 * tags: [Users]
 * requestBody:
 * required: true
 * content:
 * application/json:
 * schema:
 * type: object
 * properties:
 * email:
 * type: string
 * name:
 * type: string
 * password:
 * type: string
 * responses:
 * 201:
 * description: User created successfully
 */
router.post('/users', validate(createUserSchema), createUser)

Testing

Write tests with Jest and Supertest:

// tests/users.test.ts
import request from 'supertest'
import app from '../src/app'
import prisma from '../src/config/database'

describe('User API', () => {
 beforeEach(async () => {
 await prisma.user.deleteMany()
 })

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

 describe('POST /api/users', () => {
 it('should create a new user', async () => {
 const res = await request(app)
 .post('/api/users')
 .send({
 email: 'test@example.com',
 name: 'Test User',
 password: 'password123'
 })
 .expect(201)

 expect(res.body).toHaveProperty('id')
 expect(res.body.email).toBe('test@example.com')
 })

 it('should return 400 for invalid email', async () => {
 const res = await request(app)
 .post('/api/users')
 .send({
 email: 'invalid-email',
 name: 'Test User',
 password: 'password123'
 })
 .expect(400)

 expect(res.body).toHaveProperty('errors')
 })
 })
})

Security Best Practices

Rate Limiting

import rateLimit from 'express-rate-limit'

const limiter = rateLimit({
 windowMs: 15 * 60 * 1000, // 15 minutes
 max: 100 // limit each IP to 100 requests per windowMs
})

app.use('/api/', limiter)

Helmet for security headers

import helmet from 'helmet'
app.use(helmet())

CORS configuration

import cors from 'cors'
app.use(cors({
 origin: process.env.ALLOWED_ORIGINS?.split(','),
 credentials: true
}))

Input Sanitization

import mongoSanitize from 'express-mongo-sanitize'
app.use(mongoSanitize())

Performance Optimization

1. Response Compression

import compression from 'compression'
app.use(compression())

2. Caching

import Redis from 'ioredis'
const redis = new Redis(process.env.REDIS_URL)

async function getCachedData(key: string) {
 const cached = await redis.get(key)
 if (cached) return JSON.parse(cached)

 const data = await fetchFromDatabase()
 await redis.setex(key, 3600, JSON.stringify(data))
 return data
}

3. Database Query Optimization

// Use pagination
const users = await prisma.user.findMany({
 skip: (page - 1) * limit,
 take: limit,
 select: {
 id: true,
 email: true,
 name: true
 // Don't select sensitive fields like password
 }
})

// Use indexes
@@index([email])
@@index([createdAt])

Deployment Checklist

Environment variables configured
Database migrations run
SSL/TLS certificates installed
Rate limiting enabled
Logging configured (Winston, Morgan)
Error tracking (Sentry)
Health check endpoint
API documentation deployed
Load testing completed
Backup strategy implemented

Monitoring

// Health check endpoint
app.get('/health', async (req, res) => {
 try {
 await prisma.$queryRaw`SELECT 1`
 res.status(200).json({ status: 'healthy', timestamp: new Date() })
 } catch (error) {
 res.status(503).json({ status: 'unhealthy', error: error.message })
 }
})

Conclusion

Building production-ready APIs requires attention to:

Structure: Organized code is maintainable code
Security: Authentication, validation, and rate limiting
Errors: Proper error handling and logging
Testing: Comprehensive test coverage
Documentation: Clear API docs for consumers
Performance: Caching and optimization

The complete example code is available on .

Resources

Questions? Leave a comment below or reach out on !

Docker Deployment Guide: From Development to Production

Tue, 15 Oct 2024 00:00:00 +0000

Docker simplifies deployment by packaging your application with all dependencies. This guide covers containerizing apps, optimizing images, and production deployment.

Why Docker?

Problems Docker solves:

❌ “Works on my machine” syndrome
❌ Complex dependency management
❌ Environment inconsistencies
❌ Difficult scaling

Benefits:

✅ Consistent environments (dev = prod)
✅ Easy scaling
✅ Simplified deployment
✅ Isolation and security

Basic Dockerfile

For a Node.js application:

# Use official Node image
FROM node:18-alpine

# Set working directory
WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy application code
COPY . .

# Expose port
EXPOSE 3000

# Start application
CMD ["node", "server.js"]

Build and run:

docker build -t my-app .
docker run -p 3000:3000 my-app

Multi-Stage Builds (Optimization)

Reduce image size with multi-stage builds:

# Stage 1: Build
FROM node:18-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

# Stage 2: Production
FROM node:18-alpine

WORKDIR /app

# Copy only necessary files from builder
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./

EXPOSE 3000
CMD ["node", "dist/server.js"]

Result: Image size reduced from 800MB → 150MB!

Docker Compose for Local Development

docker-compose.yml:

version: '3.8'

services:
 app:
 build: .
 ports:
 - "3000:3000"
 environment:
 - NODE_ENV=development
 - DATABASE_URL=postgresql://user:pass@db:5432/mydb
 volumes:
 - .:/app
 - /app/node_modules
 depends_on:
 - db
 - redis

 db:
 image: postgres:15-alpine
 environment:
 - POSTGRES_USER=user
 - POSTGRES_PASSWORD=pass
 - POSTGRES_DB=mydb
 volumes:
 - postgres_data:/var/lib/postgresql/data
 ports:
 - "5432:5432"

 redis:
 image: redis:7-alpine
 ports:
 - "6379:6379"

volumes:
 postgres_data:

Start everything:

docker-compose up -d

Environment Variables

Never hardcode secrets! Use .env file:

# .env (add to .gitignore!)
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
JWT_SECRET=your-secret-key
API_KEY=your-api-key

Reference in docker-compose:

services:
 app:
 env_file:
 - .env

Production Dockerfile

Optimized for production:

FROM node:18-alpine AS builder

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install all dependencies (including devDependencies)
RUN npm ci

# Copy source
COPY . .

# Build application
RUN npm run build

# Remove devDependencies
RUN npm prune --production

# Production stage
FROM node:18-alpine

# Add non-root user
RUN addgroup -g 1001 -S nodejs && \
 adduser -S nodejs -u 1001

WORKDIR /app

# Copy built app from builder
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app/package*.json ./

# Use non-root user
USER nodejs

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
 CMD node healthcheck.js

EXPOSE 3000

CMD ["node", "dist/server.js"]

Image Optimization Tips

1. Use .dockerignore

node_modules
npm-debug.log
.git
.env
.DS_Store
*.md
.vscode
coverage
.github

2. Layer Caching

# ❌ Bad: Changes to code invalidate ALL layers
COPY . .
RUN npm ci

# ✅ Good: Package changes don't rebuild code
COPY package*.json ./
RUN npm ci
COPY . .

3. Use Alpine Images

# Large: node:18 (900MB)
FROM node:18

# Small: node:18-alpine (150MB)
FROM node:18-alpine

4. Combine RUN Commands

# ❌ Bad: Multiple layers
RUN apt-get update
RUN apt-get install -y curl
RUN apt-get clean

# ✅ Good: Single layer
RUN apt-get update && \
 apt-get install -y curl && \
 apt-get clean && \
 rm -rf /var/lib/apt/lists/*

Deploying to AWS ECS

1. Build and Push to ECR

# Authenticate Docker to ECR
aws ecr get-login-password --region us-east-1 | \
 docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com

# Build image
docker build -t my-app .

# Tag image
docker tag my-app:latest 123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:latest

# Push to ECR
docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:latest

2. ECS Task Definition

{
 "family": "my-app",
 "networkMode": "awsvpc",
 "requiresCompatibilities": ["FARGATE"],
 "cpu": "256",
 "memory": "512",
 "containerDefinitions": [
 {
 "name": "my-app",
 "image": "123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:latest",
 "portMappings": [
 {
 "containerPort": 3000,
 "protocol": "tcp"
 }
 ],
 "environment": [
 {
 "name": "NODE_ENV",
 "value": "production"
 }
 ],
 "secrets": [
 {
 "name": "DATABASE_URL",
 "valueFrom": "arn:aws:secretsmanager:..."
 }
 ],
 "logConfiguration": {
 "logDriver": "awslogs",
 "options": {
 "awslogs-group": "/ecs/my-app",
 "awslogs-region": "us-east-1",
 "awslogs-stream-prefix": "ecs"
 }
 }
 }
 ]
}

Docker Security Best Practices

1. Use Non-Root User

# Add user
RUN addgroup -g 1001 -S nodejs && \
 adduser -S nodejs -u 1001

# Switch to user
USER nodejs

2. Scan for Vulnerabilities

# Using Trivy
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
 aquasec/trivy image my-app:latest

3. Keep Base Images Updated

# ✅ Pin specific version, update regularly
FROM node:18.19.0-alpine

# ❌ Avoid 'latest' tag
FROM node:latest

4. Read-Only Filesystem

services:
 app:
 read_only: true
 tmpfs:
 - /tmp

Health Checks

Simple health check endpoint:

// healthcheck.js
const http = require('http')

const options = {
 host: 'localhost',
 port: 3000,
 path: '/health',
 timeout: 2000
}

const request = http.request(options, (res) => {
 if (res.statusCode === 200) {
 process.exit(0)
 } else {
 process.exit(1)
 }
})

request.on('error', () => {
 process.exit(1)
})

request.end()

Monitoring & Logging

Container Logs

# View logs
docker logs my-app

# Follow logs
docker logs -f my-app

# Last 100 lines
docker logs --tail 100 my-app

Docker Stats

# View resource usage
docker stats

# Specific container
docker stats my-app

Common Issues & Solutions

Issue: Image Too Large

Solution: Multi-stage builds, Alpine images, .dockerignore

Issue: Slow Builds

Solution: Optimize layer caching, use BuildKit

DOCKER_BUILDKIT=1 docker build -t my-app .

Issue: Container Won’t Start

Solution: Check logs, verify CMD/ENTRYPOINT

docker logs container-id
docker inspect container-id

CI/CD Pipeline Example (GitHub Actions)

name: Deploy

on:
 push:
 branches: [main]

jobs:
 deploy:
 runs-on: ubuntu-latest

 steps:
 - uses: actions/checkout@v3

 - name: Configure AWS credentials
 uses: aws-actions/configure-aws-credentials@v2
 with:
 aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
 aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
 aws-region: us-east-1

 - name: Login to Amazon ECR
 id: login-ecr
 uses: aws-actions/amazon-ecr-login@v1

 - name: Build and push image
 env:
 ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
 ECR_REPOSITORY: my-app
 IMAGE_TAG: ${{ github.sha }}
 run: |
 docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
 docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG

 - name: Update ECS service
 run: |
 aws ecs update-service --cluster my-cluster \
 --service my-app --force-new-deployment

Best Practices Checklist

Use multi-stage builds
Use .dockerignore
Run as non-root user
Pin base image versions
Scan for vulnerabilities
Implement health checks
Use environment variables for config
Keep images small (<500MB)
Tag images properly (not just ’latest')
Set up logging and monitoring

Resources

Conclusion

Docker streamlines deployment by:

Creating consistent environments
Simplifying dependency management
Enabling easy scaling
Improving security through isolation

Start small, optimize incrementally, and always test in staging before production!

Example repo:

Questions? Reach out on !

Tutorial |

Building a Production-Ready REST API with Node.js and Express

Table of Contents

Project Setup

Folder Structure

Database Integration

Authentication & Authorization

Error Handling

Validation

API Documentation

Testing

Security Best Practices

Performance Optimization

1. Response Compression

2. Caching

3. Database Query Optimization

Deployment Checklist

Monitoring

Conclusion

Resources

Docker Deployment Guide: From Development to Production

Why Docker?

Basic Dockerfile

Multi-Stage Builds (Optimization)

Docker Compose for Local Development

Environment Variables

Production Dockerfile

Image Optimization Tips

1. Use .dockerignore

2. Layer Caching

3. Use Alpine Images

4. Combine RUN Commands

Deploying to AWS ECS

1. Build and Push to ECR

2. ECS Task Definition

Docker Security Best Practices

1. Use Non-Root User

2. Scan for Vulnerabilities

3. Keep Base Images Updated

4. Read-Only Filesystem

Health Checks

Monitoring & Logging

Container Logs

Docker Stats

Common Issues & Solutions

Issue: Image Too Large

Issue: Slow Builds

Issue: Container Won’t Start

CI/CD Pipeline Example (GitHub Actions)

Best Practices Checklist

Resources

Conclusion