Full-Stack Architecture Patterns

Chapter 3: RESTful API Design

3.1 REST Principles

REST (Representational State Transfer) is an architectural style for designing web services. Following REST principles creates APIs that are scalable, maintainable, and easy to use.

Resource-Based URLs:

• URLs represent resources, not actions
• Use nouns, not verbs
• Hierarchical structure for relationships
• Examples: /api/users, /api/users/1/orders

HTTP Methods:

• GET: Retrieve resources (idempotent, safe)
• POST: Create new resources
• PUT: Update entire resource (idempotent)
• PATCH: Partially update resource
• DELETE: Remove resource (idempotent)

Stateless Communication:

• Each request contains all information needed
• Server doesn't store client state
• Scalable and simple
• Session state stored on client (cookies, tokens)

JSON Data Format:

• Standard format for data exchange
• Lightweight and readable
• Widely supported
• Easy to parse and generate

Uniform Interface:

• Consistent way to interact with resources
• Standard HTTP methods and status codes
• Self-descriptive messages
• Hypermedia as engine of application state (HATEOAS)

3.2 API Design Best Practices

Well-designed APIs are intuitive, consistent, and easy to use. Following best practices improves developer experience and adoption.

URL Design:

// Good: Resource-based, hierarchical
GET    /api/users
GET    /api/users/1
POST   /api/users
PUT    /api/users/1
DELETE /api/users/1

// Good: Nested resources
GET    /api/users/1/orders
POST   /api/users/1/orders

// Bad: Action-based URLs
GET    /api/getUser?id=1
POST   /api/createUser
POST   /api/deleteUser

HTTP Status Codes:

• 2xx Success: 200 OK, 201 Created, 204 No Content
• 4xx Client Error: 400 Bad Request, 401 Unauthorized, 404 Not Found
• 5xx Server Error: 500 Internal Server Error, 503 Service Unavailable

Response Format:

// Success response
{
    "data": {
        "id": 1,
        "name": "John",
        "email": "john@example.com"
    }
}

// Error response
{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid email format",
        "details": {
            "email": "Must be a valid email address"
        }
    }
}

// List response with pagination
{
    "data": [...],
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total": 100
    }
}

Versioning:

• Include version in URL: /api/v1/users
• Or use headers: Accept: application/vnd.api+json;version=1
• Maintain backward compatibility
• Document breaking changes

3.3 API Security

Security is crucial for APIs. Implement proper authentication and authorization.

Authentication Methods:

• API Keys: Simple but less secure
• JWT Tokens: Stateless, scalable
• OAuth 2.0: Industry standard
• Basic Auth: Username/password (use HTTPS)

Security Best Practices:

• Use HTTPS for all communications
• Validate and sanitize all input
• Implement rate limiting
• Use CORS properly
• Keep dependencies updated
• Log security events

3.4 API Documentation

Good documentation is essential for API adoption and usage.

Documentation Should Include:

• API overview and authentication
• All endpoints with examples
• Request/response formats
• Error codes and messages
• Code examples in multiple languages
• Rate limits and quotas

Documentation Tools:

• OpenAPI/Swagger: Industry standard
• Postman: API testing and documentation
• API Blueprint: Markdown-based
• RAML: RESTful API Modeling Language