API Design First Principles

# API Design Rules

## Naming
- Use camelCase for field names in JSON responses.
- Use plural nouns for resource collections: `/users`, `/posts`.
- Use verb-noun for actions that don't map to CRUD: `/auth/sign-in`, `/reports/generate`.
- tRPC router names are singular nouns: `user`, `post`, `comment`.
- tRPC procedure names are verbs: `list`, `getById`, `create`, `update`, `delete`.

## Response Shape
All API responses follow this envelope:
```typescript
// Success
{ data: T }

// List with pagination
{ data: T[], nextCursor: string | null, totalCount?: number }

// Error
{ error: { code: string, message: string, details?: unknown } }

Error Handling

• Use appropriate HTTP status codes (don't return 200 for errors).
• Error codes are SCREAMING_SNAKE_CASE: NOT_FOUND, VALIDATION_ERROR.
• Include actionable error messages for client developers.
• Never expose internal errors, stack traces, or database details.
• Rate limit responses include Retry-After header.

Pagination

• Use cursor-based pagination by default (better for real-time data).
• Cursor is an opaque string (base64-encoded ID or timestamp).
• Default page size: 20. Maximum: 100. Always validate limit input.

Validation

• Validate all inputs with Zod schemas at the API boundary.
• Coerce string numbers from query params: z.coerce.number().
• Trim and sanitize string inputs.
• Return 400 with field-level errors for validation failures.