RESTful 接口规范

问题

RESTful 接口规范是什么？如何设计符合规范的接口？

解答

RESTful 接口规范是一种基于 REST（Representational State Transfer）架构的 Web 服务接口设计风格。

资源（Resources）

将系统中的所有事物视为资源，每个资源通过唯一的 URL 标识。

GET /api/users/123
GET /api/articles/456

统一接口（Uniform Interface）

使用标准的 HTTP 方法操作资源：

GET    /api/users      # 获取用户列表
POST   /api/users      # 创建用户
GET    /api/users/123  # 获取指定用户
PUT    /api/users/123  # 更新用户
DELETE /api/users/123  # 删除用户

使用标准 HTTP 状态码表示结果：

// 200 - 成功
// 201 - 创建成功
// 400 - 请求错误
// 404 - 资源不存在
// 500 - 服务器错误

使用合适的 MIME 类型传输数据：

Content-Type: application/json

无状态（Stateless）

每个请求包含完整信息，服务器不保存客户端状态：

// 每次请求都携带认证信息
fetch('/api/users', {
  headers: {
    'Authorization': 'Bearer token123'
  }
});

客户端-服务器分离

客户端和服务器通过标准接口交互，可独立演化。

可缓存性（Cacheability）

对不常变化的数据使用缓存：

Cache-Control: max-age=3600
ETag: "abc123"

关键点

• 使用 URL 标识资源，用 HTTP 方法表示操作（GET/POST/PUT/DELETE）
• 每个请求包含完整信息，服务器不保存客户端状态
• 使用标准 HTTP 状态码（200/404/500）和 JSON 格式传输数据
• 合理使用缓存机制提升性能
• 客户端和服务器通过统一接口分离，便于独立演化和系统集成