RESTful API Design with Express.js

REST Principles and Resource Naming

REST uses HTTP methods to represent actions: GET (read), POST (create), PUT/PATCH (update), DELETE (remove). Resources should be nouns (e.g. /users, /orders) and use plural form. Nest resources only one level when it makes sense: /orders/123/items.

Structuring an Express API

Organize routes by resource or domain. Use router modules and mount them under a base path. Keep route handlers thin—delegate business logic to services. Middleware order matters: apply body parsing, logging, auth, and then route-specific middleware.

app.use('/api/v1/users', userRoutes);
app.use('/api/v1/orders', orderRoutes);
app.use(errorHandler);

Validation and Error Handling

Validate request body, params, and query with a library like Joi, Zod, or express-validator. Return consistent error responses with appropriate HTTP status codes (400, 401, 404, 500) and a unified shape such as { error: { code, message } }. Use a central error-handling middleware to catch and format errors.

Authentication and Rate Limiting

Protect routes with middleware that verify JWT or session. Use rate limiting (e.g. express-rate-limit) to prevent abuse. Apply different limits for auth vs public endpoints. Return 429 with Retry-After when limits are exceeded.

API Versioning

Version via URL path (/api/v1/) or headers. URL versioning is simple and cache-friendly. When introducing breaking changes, release a new version and deprecate the old one with clear documentation and sunset headers.

Consistency in naming, status codes, and response shape makes your API predictable and easier to integrate and maintain.