A RESTful API (Representational State Transfer Application Programming Interface) is a way for systems to communicate over the web using HTTP methods. It is based on the principles of REST, an architectural style that defines a set of constraints and principles for creating web services.

🧩 核心概念

概念说明
资源（Resource）API 操作的对象，如用户、文章等。每个资源使用唯一的 URL 进行标识。
HTTP 动词用于定义操作类型：GET（读取）、POST（创建）、PUT（更新）、DELETE（删除）。
URI（Uniform Resource Identifier）用于指定资源的位置。例如：/users/123 表示用户 ID 为 123 的资源。
无状态（Stateless）每次请求都必须包含完成该请求所需的所有信息，服务器不会记住之前的请求状态。

📡 常用 HTTP 方法与操作含义

方法用途示例 URI描述
GET获取资源/users获取所有用户
GET获取单个资源/users/1获取 ID 为 1 的用户
POST创建资源/users创建一个新用户
PUT更新资源（整体替换）/users/1更新 ID 为 1 的用户
PATCH更新资源（局部修改）/users/1修改用户的一部分属性
DELETE删除资源/users/1删除 ID 为 1 的用户

🛠️ 示例：用户资源的 RESTful API 设计

假设我们有一个管理用户信息的系统：

GET /users              -> 获取用户列表
GET /users/1            -> 获取用户 1 的详细信息
POST /users             -> 创建新用户
PUT /users/1            -> 更新用户 1 的所有信息
PATCH /users/1          -> 局部更新用户 1
DELETE /users/1         -> 删除用户 1

✅ RESTful API 的设计原则

  1. 使用名词而非动词表示资源（URL 中不要用 create/get/delete）
  2. 使用 HTTP 状态码表示结果（如 200、201、204、400、404、500）
  3. 保持接口简洁、可预测
  4. 支持分页、过滤、排序
  5. 返回标准 JSON 响应格式

🧪 示例响应

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com"
}

📘 参考资料