RESTful API

RESTful API 是把 HTTP API 设计建立在 REST 资源、表示、无状态、统一接口、缓存与分层等约束上的实践风格；重点是资源语义和 HTTP 语义，而不是机械套 CRUD URL。

#backend #concept #evergreen

[!info] related notes

所属 MOC: 后端开发 MOC

上层概念: 接口规范

相关概念: API版本管理, OpenAPI 与 Swagger, 接口幂等设计, HTTP状态码

相关实践: nodejs后端api测试搭建集成测试框架

RESTful API 设计规范

REST 是一种架构风格，不是标准或协议，而是一组设计原则和约束条件

📖 核心概念

REST (Representational State Transfer) 由 Roy Fielding 在 2000 年的博士论文中提出，是一种面向资源的架构风格。

六大约束

客户端-服务器 - 关注点分离
无状态 - 每个请求包含所有必要信息
可缓存 - 响应可被缓存
统一接口 - 资源导向、HTTP 动词、自描述消息
分层系统 - 客户端不知道直接连接还是中间层
按需代码（可选） - 服务端可返回可执行代码

🎯 设计原则

(1) 资源导向

所有事物都抽象为资源，使用名词而非动词
使用复数形式表示资源集合，如/users而非/user
资源使用 URI 唯一标识，如/users/123

(2) HTTP 方法语义化

GET：获取资源（安全且幂等）
POST：创建资源（非幂等）
PUT：完整更新资源（幂等）
PATCH：部分更新资源
DELETE：删除资源（幂等）

(3) 状态码规范

2xx 成功：
- 200 OK - 通用成功
- 201 Created - 资源创建成功
- 204 No Content - 成功但无返回体
3xx 重定向
4xx 客户端错误：
- 400 Bad Request - 请求错误
- 401 Unauthorized - 未认证
- 403 Forbidden - 无权限
- 404 Not Found - 资源不存在
5xx 服务端错误：
- 500 Internal Server Error - 通用服务端错误
- 503 Service Unavailable - 服务不可用

(4) 版本控制

URI 中包含版本：/api/v1/users
或通过 Accept 头指定：Accept: application/vnd.myapi.v1+json

(5) 过滤、排序、分页

过滤：/users?role=admin
排序：/users?sort=-created_at,username
分页：/users?page=2&limit=20

(6) 响应格式

统一使用 JSON 格式
包含资源本身和可能的元数据

错误响应标准化：

{
  "error": {
    "code": "invalid_param",
    "message": "Invalid email format",
    "details": {
      "email": "Should be a valid email address"
    }
  }
}

(7) 超媒体(HATEOAS)

响应中包含相关资源的链接

示例：

{
  "id": 123,
  "name": "John",
  "links": [
    {
      "rel": "self",
      "href": "/users/123"
    },
    {
      "rel": "friends",
      "href": "/users/123/friends"
    }
  ]
}

3. 其他最佳实践

安全性：
- 使用 HTTPS
- 敏感数据不在 URL 中传递
- 适当的认证机制（如 JWT、OAuth）
性能：
- 支持缓存（ETag、Last-Modified）
- 考虑使用 gzip 压缩
- 避免过度获取数据（支持字段选择）
文档：
- 提供清晰、完整的 API 文档
- 使用 Swagger/OpenAPI 等工具
命名规范：
- 使用小写字母和连字符-（而非下划线_）
- 保持一致性

4. RESTful 与非 RESTful 对比

RESTful:

GET /users/123
PUT /users/123
DELETE /users/123

非 RESTful:

GET /getUser?id=123
POST /updateUser
POST /deleteUser

作为开发者，我会遵循这些规范来设计易于理解、维护和扩展的 API，同时也会根据实际业务需求进行适当调整，在规范性和实用性之间取得平衡。

学习检查

不看正文回答：

REST 为什么是一种 architecture style，而不是 HTTP API 的强制标准？
client-server、stateless、cacheable、uniform interface、layered system、code-on-demand 六个约束分别解决什么？
为什么“URL 用复数名词 + GET/POST/PUT/DELETE”只能算 REST 风格的一部分？
HTTP method 的 safety / idempotency 与业务实现有什么关系？
PUT 与 PATCH 的语义差异为什么不能只记成“全量 vs 部分”四个字？
HATEOAS 为什么属于 REST 约束语境，但现实 API 经常只实现其中一部分？
RESTful 风格与 API Contract 是什么关系？
给一个“取消订单”操作，分别设计资源状态更新和 command-style endpoint，说明你为什么选择其中一种。