概述

RESTful API 设计应遵循一致、简洁、易于理解的原则，确保API的可用性和可维护性。

基本原则

1. 使用名词而非动词：端点应表示系统中的实体，而不是对它们执行的操作。

   允许极少数例外(login/logout), 即是login/logout也可以用sessions/tokens这个端点替代.

2. 保持简洁明了：端点路径应直观易懂，避免过长或过于复杂的URL。

3. 使用标准HTTP方法：如GET（读取）、POST（创建）、PUT（更新）、DELETE（删除）。

4. 状态代码表示操作结果：如200（成功）、404（未找到）、500（服务器错误）等。

5. 遵循资源层次结构：资源和子资源应以层次结构的方式组织。

端点设计

一般结构

/资源名/资源ID/子资源名/子资源ID

示例

• 获取用户列表：

  GET /users
  

• 获取特定用户信息：

  GET /users/{userId}
  

• 创建新用户：

  POST /users
  

• 更新用户信息：

  PUT /users/{userId}
  

• 删除用户：

  DELETE /users/{userId}
  

• 获取用户的订单列表：

  GET /users/{userId}/orders
  

• 获取特定订单信息：

  GET /users/{userId}/orders/{orderId}
  

过滤、排序、分页和搜索

• 过滤：使用查询参数来过滤列表。

  GET /users?role=admin
  

• 排序：允许使用查询参数进行排序。

  GET /users?sort=age_asc
  

• 分页：使用limit和offset参数进行分页。

  GET /users?limit=10&offset=0
  

• 搜索：提供搜索功能。

  GET /users?search=张三
  

安全性和授权

• 使用OAuth2.0、JWT等机制进行用户认证和授权。
• 确保敏感数据的传输使用HTTPS。

版本控制

• 将API版本号包含在URL中。

  /v1/users
  

错误处理

• 返回统一格式的错误响应，包括错误代码和描述信息。

  {
    "error": "NotFound",
    "message": "User not found."
  }