REST API Design Best Practices with Node.js and Express

A well-designed API is the backbone of any modern application. Whether it powers a mobile app, a SaaS dashboard, or a third-party integration, the quality of your API directly impacts developer experience, application performance, and long-term maintainability.

Consistent URL Structure

RESTful APIs should follow predictable naming conventions. Use nouns for resources, HTTP methods for actions, and nest related resources logically.

1GET    /api/v1/users          → List all users
2GET    /api/v1/users/:id      → Get a single user
3POST   /api/v1/users          → Create a new user
4PATCH  /api/v1/users/:id      → Update a user
5DELETE /api/v1/users/:id      → Delete a user
6
7GET    /api/v1/users/:id/orders    → Get user's orders
8POST   /api/v1/users/:id/orders    → Create order for user

Request Validation with Zod

Never trust incoming data. Use a schema validation library like Zod to validate request bodies, query parameters, and URL params before they reach your business logic.

1import { z } from 'zod';
2
3export const createUserSchema = z.object({
4  name: z.string().min(2).max(100),
5  email: z.string().email(),
6  password: z.string().min(8).max(128),
7  role: z.enum(['admin', 'manager', 'member']).default('member'),
8});
9
10export const updateUserSchema = createUserSchema.partial();
11
12export type CreateUserInput = z.infer<typeof createUserSchema>;

Standardized Error Responses

Consistent error formatting makes debugging easier for frontend developers and API consumers. Every error response should include a status code, message, and optional field-level details.

1// Success Response
2{
3  "success": true,
4  "data": { "id": 1, "name": "John Doe", "email": "john@example.com" },
5  "meta": { "page": 1, "total": 50, "perPage": 10 }
6}
7
8// Error Response
9{
10  "success": false,
11  "error": {
12    "code": "VALIDATION_ERROR",
13    "message": "Request validation failed",
14    "details": [
15      { "field": "email", "message": "Invalid email format" },
16      { "field": "password", "message": "Must be at least 8 characters" }
17    ]
18  }
19}

Authentication with JWT

JSON Web Tokens remain the standard for stateless API authentication. Implement access tokens with short expiry (15 minutes) and refresh tokens stored in HTTP-only cookies for a secure, scalable auth system.

Rate Limiting and Security

Protect your API with rate limiting, strict CORS rules, secure headers, and input sanitization. In production environments, these controls are baseline engineering requirements rather than optional hardening.

• Rate limit: 100 requests per 15 minutes per IP for public endpoints
• Use helmet() middleware for secure HTTP headers
• Enable CORS only for trusted origins
• Sanitize all user input to prevent NoSQL injection and XSS
• Log all requests with correlation IDs for debugging

Conclusion

A well-designed REST API is an investment in your application's future. By following consistent conventions, validating inputs rigorously, and implementing proper security measures from the start, you create an API that is a pleasure to work with — for your team and for every developer who consumes it.