API Module Standards

This file supplements root CLAUDE.md for everything in /src/api/. Memory files are concatenated, not overridden — the root CLAUDE.md still applies, and Claude Code loads this file on demand when it reads files in this subtree.

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

Last Updated: August 4, 2026 Claude Code Version: 2.1.220 Sources: - https://code.claude.com/docs/en/memory Compatible Models: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5