REST（Representational State Transfer）是一种基于 HTTP 协议的架构风格，广泛用于设计和调用 Web API。以下是使用 REST 的核心方法及实践指南：

---

一、REST 核心原则

1. 资源（Resources）

   • 所有数据或服务抽象为资源（如用户、商品），每个资源有唯一标识符（URI）。
   • 示例 URI：/users/123 表示 ID 为 123 的用户。

2. HTTP 方法

   • 通过标准 HTTP 方法操作资源：
     • GET：获取资源。
     • POST：创建资源。
     • PUT/PATCH：更新资源（全量/部分更新）。
     • DELETE：删除资源。

3. 无状态（Stateless）

   • 每个请求必须包含完成操作所需的所有信息，服务器不保存客户端状态。

4. 返回格式

   • 数据通常以 JSON 或 XML 格式传输，通过 Content-Type 标头声明（如 application/json）。

---

二、设计 RESTful API 的最佳实践

1. URI 设计规范

• 使用名词复数表示资源，层级清晰：
  • GET /users（获取所有用户）
  • GET /users/123/orders（获取用户 123 的订单）
• 避免动词，用 HTTP 方法表示操作：
  • ❌ /getUser?id=123 → ✅ GET /users/123
• 使用小写字母和连字符（-），而非下划线（_）。

2. HTTP 状态码

• 常用状态码：
  • 200 OK：成功。
  • 201 Created：资源创建成功。
  • 400 Bad Request：客户端请求错误。
  • 401 Unauthorized：未认证。
  • 404 Not Found：资源不存在。
  • 500 Internal Server Error：服务器内部错误。

3. 请求与响应示例

• GET 获取资源

  GET /users/123 HTTP/1.1
  Host: api.example.com
  Accept: application/json

  // 响应
  HTTP/1.1 200 OK
  {
    "id": 123,
    "name": "Alice"
  }

• POST 创建资源

  POST /users HTTP/1.1
  Content-Type: application/json
  {
    "name": "Bob"
  }

  // 响应
  HTTP/1.1 201 Created
  Location: /users/124

• PUT 更新资源

  PUT /users/123 HTTP/1.1
  Content-Type: application/json
  {
    "name": "Alice Smith"
  }

4. 版本控制

• 在 URI 或请求头中标记 API 版本：
  • URI 方式：/v1/users
  • 请求头方式：Accept: application/vnd.myapi.v1+json

---

三、调用 REST API 的工具

1. 命令行工具（cURL）

   curl -X GET https://api.example.com/users/123
   curl -X POST -H "Content-Type: application/json" -d '{"name":"Bob"}' https://api.example.com/users

2. 图形化工具

   • Postman、Insomnia：可视化发送请求并测试 API。

3. 代码调用（以 Python 为例）

   import requests
   
   # GET 请求
   response = requests.get("https://api.example.com/users/123")
   print(response.json())
   
   # POST 请求
   data = {"name": "Bob"}
   response = requests.post("https://api.example.com/users", json=data)
   print(response.status_code)

---

四、安全性与认证

1. HTTPS

   • 始终使用 HTTPS 加密通信。

2. 认证机制

   • API 密钥：通过请求头传递（如 X-API-Key: your-key）。
   • OAuth 2.0：使用 Bearer Token（Authorization: Bearer <token>）。
   • JWT：在请求头中携带 Token（Authorization: Bearer <JWT>）。

---

五、错误处理

• 响应中返回具体错误信息：

  {
    "error": "Invalid request",
    "code": 400,
    "details": "Missing required field: name"
  }

---

六、常见框架

• Node.js：Express、Fastify。
• Python：Flask、Django REST Framework。
• Java：Spring Boot。
• Ruby：Ruby on Rails。

---

总结

REST 的关键在于合理利用 HTTP 协议的特性，通过清晰的 URI 设计、标准的方法和状态码实现资源操作。结合工具和框架，可快速构建高效、易用的 API。