api-architecture

API Architecture

Master architectural concerns that apply across all API types for production-ready systems.

When to Use This Skill

• Planning API versioning strategies
• Implementing authentication and authorization
• Setting up rate limiting and quotas
• Designing error handling strategies
• Planning monitoring and observability
• Generating API documentation
• Securing APIs against attacks
• Implementing caching strategies

API Versioning

URL Versioning (Recommended)

Clear and easy to route: /api/v1/users, /api/v2/users

Header Versioning

Clean URLs: Accept: application/vnd.api+json; version=2

Query Parameter Versioning

Easy to test: GET /api/users?version=2

Security Best Practices

Authentication

Bearer Token (JWT):

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
401 Unauthorized - Missing/invalid token
403 Forbidden - Valid token, insufficient permissions

API Keys:

X-API-Key: your-api-key-here

Authorization Patterns

• Role-based access control (RBAC)
• Attribute-based access control (ABAC)
• Scope-based permissions (OAuth 2.0)

Input Validation

• Validate all input at API boundaries
• Use schemas for validation (Pydantic, JSON Schema)
• Sanitize user input to prevent injection attacks
• Validate file uploads

Rate Limiting

Implementation Pattern

class RateLimiter:
    def __init__(self, calls: int, period: int):
        self.calls = calls
        self.period = period
        self.cache = {}

    def check(self, key: str) -> bool:
        now = datetime.now()
        if key not in self.cache:
            self.cache[key] = []

        self.cache[key] = [
            ts for ts in self.cache[key]
            if now - ts < timedelta(seconds=self.period)
        ]

        if len(self.cache[key]) >= self.calls:
            return False

        self.cache[key].append(now)
        return True

Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 742
X-RateLimit-Reset: 1640000000

429 Too Many Requests
Retry-After: 3600

Monitoring and Observability

Health Check Endpoints

@app.get("/health")
async def health_check():
    return {"status": "healthy", "version": "1.0.0"}

@app.get("/health/detailed")
async def detailed_health():
    return {
        "status": "healthy",
        "checks": {
            "database": await check_database(),
            "cache": await check_cache()
        }
    }

Logging Strategy

• Log all API requests/responses
• Include request ID for tracing
• Log authentication/authorization events
• Log errors with full context
• Use structured logging (JSON format)

Metrics to Track

• Request count by endpoint
• Response times (latency)
• Error rates by status code
• Active connections
• Rate limit usage

Caching Strategies

HTTP Caching

Cache-Control: public, max-age=3600     # Client caching
Cache-Control: no-cache, no-store       # No caching

ETag: "hash"
If-None-Match: "hash"
→ 304 Not Modified

Server-Side Caching

• In-memory caching (Redis)
• Database query caching
• API response caching
• Cache invalidation strategies

Error Handling

Standardized Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [{"field": "email", "message": "Invalid"}],
    "timestamp": "2025-10-16T12:00:00Z",
    "path": "/api/users"
  }
}

Status Code Guidelines

• 2xx Success: 200, 201, 204
• 4xx Errors: 400, 401, 403, 404, 422, 429
• 5xx Server: 500, 503

Documentation Standards

OpenAPI/Swagger

app = FastAPI(
    title="My API",
    docs_url="/docs",
    redoc_url="/redoc"
)

@app.get("/api/users/{user_id}", tags=["Users"])
async def get_user(user_id: str):
    """Retrieve user by ID."""
    pass

GraphQL Documentation

• GraphQL introspection (free documentation)
• Use @deprecated for backward compatibility
• Document complex types with descriptions

Best Practices Summary

1. Versioning - Plan for breaking changes early
2. Security - Implement defense in depth
3. Rate Limiting - Protect from abuse
4. Monitoring - Observe production APIs
5. Documentation - Keep in sync with code
6. Error Handling - Standardize responses
7. Caching - Balance freshness and performance
8. Logging - Collect actionable data
9. Metrics - Track important signals
10. Testing - Security and performance tests

Cross-Skill References

• rest-api-design - REST-specific patterns
• graphql-api-design - GraphQL-specific patterns
• api-testing - Testing security and monitoring