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.