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:

{
  "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