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