API Architecture Skill | Agent Skills

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

Versioning - Plan for breaking changes early
Security - Implement defense in depth
Rate Limiting - Protect from abuse
Monitoring - Observe production APIs
Documentation - Keep in sync with code
Error Handling - Standardize responses
Caching - Balance freshness and performance
Logging - Collect actionable data
Metrics - Track important signals
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

Agent Skills: API Architecture

Install this agent skill to your local

Skill Files