Node.js – API Design

Rules

• Use nouns for resources: /users, /orders — not /getUser
• HTTP methods: GET (read), POST (create), PUT/PATCH (update), DELETE (remove)
• Return consistent response shapes: { data, error, meta }
• Validate all inputs with Joi or Zod
• Paginate all list endpoints with limit and offset
• Always version your API: /api/v1/users

URL Structure

GET    /api/v1/users          — list users
GET    /api/v1/users/:id      — get one user
POST   /api/v1/users          — create user
PATCH  /api/v1/users/:id      — update user
DELETE /api/v1/users/:id      — delete user

Consistent Response Shape

// Success
res.json({
  data: users,
  error: null,
  meta: { total: 100, limit: 10, offset: 0 }
});

// Error
res.status(400).json({
  data: null,
  error: 'Validation failed: email is required'
});