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 !

E-Commerce Platform

Fri, 15 Nov 2024 00:00:00 +0000

A modern, scalable e-commerce platform built from scratch with performance and user experience as top priorities.

Overview

Built a complete e-commerce solution for a mid-sized retail company looking to expand online. The platform handles everything from product catalog management to payment processing and order fulfillment.

Key Features

Customer-Facing

Product Catalog - Dynamic filtering, sorting, and search with instant results
Shopping Cart - Real-time inventory checking and price calculations
Checkout - Secure payment processing via Stripe with Apple Pay/Google Pay support
Order Tracking - Real-time order status updates with email notifications
User Accounts - Profile management, order history, and saved addresses

Admin Dashboard

Inventory Management - Real-time stock tracking and low-stock alerts
Order Management - Bulk order processing and fulfillment workflow
Analytics - Sales dashboards, customer insights, and revenue reporting
Product Management - Easy product creation with image uploads and variants

Technical Highlights

Performance Optimization

Implemented Redis caching reducing database queries by 70%
Optimized images with WebP format and lazy loading
Server-side rendering for critical pages improving SEO and load times
CDN integration for global content delivery

Scalability

Microservices architecture allowing independent scaling
Horizontal scaling with load balancing
Database read replicas for improved query performance
Message queues for async processing (order emails, inventory updates)

Security

JWT authentication with refresh tokens
Rate limiting to prevent abuse
Input validation and sanitization
PCI-compliant payment processing via Stripe

Architecture

┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ React SPA │────▶│ REST API │────▶│ PostgreSQL │
└─────────────┘ │ (Express) │ └─────────────┘
 └──────┬───────┘
 │
 ┌──────▼───────┐
 │ Redis │
 │ (Cache) │
 └──────────────┘

Challenges & Solutions

Challenge 1: Inventory Sync

Problem: Multiple users buying same product simultaneously causing overselling

Solution: Implemented optimistic locking with Redis to ensure inventory accuracy during concurrent purchases

Challenge 2: Payment Processing

Problem: Handling payment failures gracefully while maintaining order integrity

Solution: Built robust state machine for order processing with automatic retry logic and customer notifications

Challenge 3: Performance at Scale

Problem: Slow page loads during traffic spikes

Solution: Implemented multi-layer caching strategy (CDN, Redis, in-memory) and database query optimization

Results

Performance: 60% faster page load times compared to previous platform
Conversion: 25% increase in conversion rate due to improved UX
Uptime: 99.9% uptime over 6 months in production
Scale: Successfully handled Black Friday with 10k concurrent users
Revenue: Processing over $50k in monthly transactions

Tech Stack Details

Frontend

React 18 with TypeScript
Tailwind CSS for styling
React Query for data fetching
React Hook Form for forms

Backend

Node.js with Express
PostgreSQL with Prisma ORM
Redis for caching and sessions
Bull for job queues

Infrastructure

Docker containers
AWS EC2 for hosting
AWS S3 for image storage
Cloudflare CDN
GitHub Actions for CI/CD

Payment & Services

Stripe for payments
SendGrid for emails
Sentry for error tracking

Future Improvements

Mobile app (React Native)
Multi-language support
Wishlist and product recommendations
Live chat support
Advanced analytics dashboard

Screenshots

(Screenshots would go here in production)

Lessons Learned

Start with Performance: Built with performance in mind from day one rather than optimizing later
Testing Matters: Comprehensive test suite caught critical bugs before production
Monitor Everything: Proper logging and monitoring essential for maintaining uptime
User Feedback: Regular user testing revealed UX issues we wouldn’t have found otherwise

Project Status: ✅ Live in Production
GitHub:
Demo:

Backend |

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

E-Commerce Platform

Overview

Key Features

Customer-Facing

Admin Dashboard

Technical Highlights

Performance Optimization

Scalability

Security

Architecture

Challenges & Solutions

Challenge 1: Inventory Sync

Challenge 2: Payment Processing

Challenge 3: Performance at Scale

Results

Tech Stack Details

Future Improvements

Screenshots

Lessons Learned