API Module Standards

This file overrides root CLAUDE.md for everything in /src/api/

API-Specific Standards

Request Validation

• Use Zod for schema validation
• Always validate input
• Return 400 with validation errors
• Include field-level error details

Authentication

• All endpoints require JWT token
• Token in Authorization header
• Token expires after 24 hours
• Implement refresh token mechanism

Response Format

All responses must follow this structure:

{
  "success": true,
  "data": { /* actual data */ },
  "timestamp": "2025-11-06T10:30:00Z",
  "version": "1.0"
}

Error responses:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "User message",
    "details": { /* field errors */ }
  },
  "timestamp": "2025-11-06T10:30:00Z"
}

Pagination

• Use cursor-based pagination (not offset)
• Include hasMore boolean
• Limit max page size to 100
• Default page size: 20

Rate Limiting

• 1000 requests per hour for authenticated users
• 100 requests per hour for public endpoints
• Return 429 when exceeded
• Include retry-after header

Caching

• Use Redis for session caching
• Cache duration: 5 minutes default
• Invalidate on write operations
• Tag cache keys with resource type