api-conventions

# API Design Conventions These are the API design standards for our project. Apply these conventions whenever working with API endpoints. ## URL Naming - Use plural nouns for resources: `/users`, `/orders`, `/products` - Use kebab-case for multi-word resources: `/order-items`, `/user-profiles` - Nested resources for belongsTo relationships: `/users/{id}/orders` - Maximum two levels of nesting; beyond that, use query parameters - Use query parameters for filtering: `/orders?status=active&limit=20` ## Response Format All API responses must follow this structure: ```json { "data": {}, "error": null, "meta": { "page": 1, "limit": 20, "total": 100 } } ``` - `data`: 成功时返回的业务数据 - `error`: 错误时返回错误对象 `{ code, message, details }`，成功时为 `null` - `meta`: 分页和元信息，列表接口必须返回 ## HTTP Status Codes - 200: 成功返回数据 - 201: 成功创建资源 - 400: 请求参数错误 - 401: 未认证 - 403: 无权限 - 404: 资源不存在 - 422: 业务逻辑错误 - 500: 服务器内部错误 ## Authentication - All endpoints require Bearer token unless explicitly marked as public - Public endpoints must be documented with `@public` annotation - Token format: `Authorization: Bearer <jwt-token>` ## Versioning - API version in URL path: `/api/v1/users` - Breaking changes require new version