RESTful API Design — Principles and Best Practices

REST Principles

• Stateless: Each request contains all information needed
• Resource-based: URLs represent resources (nouns, not verbs)
• HTTP methods: GET, POST, PUT, PATCH, DELETE map to CRUD
• Uniform interface: Consistent URL patterns and responses

Resource Naming

# Good
GET    /api/v1/users
POST   /api/v1/users
GET    /api/v1/users/123
PUT    /api/v1/users/123
DELETE /api/v1/users/123

# Nested resources
GET    /api/v1/users/123/posts
GET    /api/v1/posts/456/comments

# Filtering with query params
GET    /api/v1/users?role=admin&sort=-createdAt

Response Format

// Success
{
  "status": "success",
  "data": { "id": 123, "name": "Alice" }
}

// List with pagination
{
  "status": "success",
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

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

Versioning

# URL versioning (most common)
/api/v1/users
/api/v2/users

# Header versioning
GET /api/users
Accept: application/vnd.myapp.v2+json

Rate Limiting

const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
  message: 'Too many requests'
});

app.use('/api/', limiter);