API Design Patterns

REST Endpoint Design

GET    /users          - List users
GET    /users/:id      - Get single user
POST   /users          - Create user
PUT    /users/:id      - Update user (full)
PATCH  /users/:id      - Update user (partial)
DELETE /users/:id      - Delete user

Response Structure

// Success
{
  "data": { "id": 1, "name": "John" },
  "meta": { "timestamp": "2024-01-01T00:00:00Z" }
}

// Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [{ "field": "email", "issue": "required" }]
  }
}

HTTP Status Codes

Input Validation

// Always validate at API boundary
function createUser(req, res) {
  const { email, name } = req.body;

  if (!email || !isValidEmail(email)) {
    return res.status(400).json({
      error: { code: 'VALIDATION_ERROR', message: 'Invalid email' }
    });
  }

  // Proceed with valid data
}

Authentication Patterns

// JWT in header
Authorization: Bearer <token>

// Middleware
function authMiddleware(req, res, next) {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ error: 'Unauthorized' });

  try {
    req.user = verifyToken(token);
    next();
  } catch {
    res.status(401).json({ error: 'Invalid token' });
  }
}

Pagination

GET /users?page=1&limit=20

Response:
{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Security Checklist

• Validate all inputs
• Use HTTPS only
• Implement rate limiting
• Sanitize outputs (prevent XSS)
• Use parameterized queries (prevent SQL injection)
• Implement proper CORS
• Don't expose sensitive data in errors
• Log security events