RESTful API Design Principles

Core Principles

1. Stateless

• Each request contains all information needed to process it
• Server doesn't store client context between requests
• Improves scalability and reliability

2. Client-Server Architecture

• Separation of concerns
• Client handles UI, server handles data storage
• Allows independent evolution of both sides

3. Cacheable

• Responses should be cacheable when appropriate
• Improves performance and scalability
• Use proper cache headers

4. Uniform Interface

• Consistent naming conventions
• Standard HTTP methods
• Self-descriptive messages

HTTP Methods

# CRUD Operations
GET    /users          # Read all users
GET    /users/123      # Read specific user
POST   /users          # Create new user
PUT    /users/123      # Update entire user
PATCH  /users/123      # Partial update
DELETE /users/123      # Delete user

Resource Naming

Good Examples

# Use nouns, not verbs
GET /users
POST /users
GET /users/123/orders

# Hierarchical relationships
GET /users/123/orders/456
GET /categories/electronics/products

# Query parameters for filtering
GET /users?role=admin&status=active
GET /products?category=electronics&sort=price&order=desc

HTTP Status Codes

Success (2xx)

• 200 OK - Successful GET, PUT, PATCH
• 201 Created - Successful POST
• 204 No Content - Successful DELETE

Client Errors (4xx)

• 400 Bad Request - Invalid request data
• 401 Unauthorized - Authentication required
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource doesn't exist
• 409 Conflict - Resource conflict

Server Errors (5xx)

• 500 Internal Server Error - Generic server error
• 503 Service Unavailable - Temporary unavailability

API Versioning

URL Versioning

GET /api/v1/users
GET /api/v2/users

Header Versioning

GET /api/users
Accept: application/vnd.api+json;version=1

Pagination

Offset-based Pagination

GET /users?page=2&limit=20

# Response
{
    "data": [...],
    "pagination": {
        "page": 2,
        "limit": 20,
        "total": 150,
        "pages": 8,
        "hasNext": true,
        "hasPrev": true
    }
}

Error Handling

Consistent Error Format

{
    "success": false,
    "error": {
        "code": 400,
        "message": "Validation failed",
        "details": [
            "Email is required",
            "Password too short"
        ],
        "timestamp": "2023-12-01T10:00:00Z"
    }
}

Security Best Practices

1. Authentication: JWT tokens, OAuth 2.0
2. Authorization: Role-based access control
3. HTTPS: Encrypt data in transit
4. Rate Limiting: Prevent abuse
5. Input Validation: Sanitize all inputs
6. CORS: Configure properly for web apps