REST API 设计
目录
概述
设计直观、一致的 REST API,并遵循面向资源的架构的行业最佳实践。
何时使用
- 设计新的 RESTful API
- 创建端点结构
- 定义请求/响应格式
- 实施 API 版本控制
- 记录 API 规范
- 重构现有 API
快速入门
最小工作示例:
✅ 正确的资源命名(名词,复数)
GET /api/users
GET /api/users/123
GET /api/users/123/orders
POST /api/products
DELETE /api/products/456
❌ 错误的资源命名(动词,不一致)
GET /api/getUsers
POST /api/createProduct
GET /api/user/123 (单复数不一致)
参考指南
详细实现在 references/ 目录中:
| 指南 | 内容 |
|---|---|
| 资源命名 | 资源命名、HTTP 方法和操作 |
| 请求示例 | 请求示例 |
| 查询参数 | 查询参数 |
| 响应格式 | 响应格式 |
| HTTP 状态码 | HTTP 状态码、API 版本控制、身份验证和安全性、速率限制标头 |
| OpenAPI 文档 | OpenAPI 文档 |
| 完整示例:Express.js | Express.js 完整示例 |
最佳实践
✅ 应该做
- 使用名词来表示资源,而不是动词
- 集合使用复数名称
- 与命名约定保持一致
- 返回适当的 HTTP 状态码
- 包括集合的分页
- 提供过滤和排序选项
- 版本化你的 API
- 使用 OpenAPI 进行详细文档
- 使用 HTTPS
- 实施速率限制
- 提供清晰的错误消息
- 使用 ISO 8601 日期格式
❌ 不应该做
- 在端点名称中使用动词
- 错误地返回 200
- 不必要地暴露内部 ID
- 过度嵌套资源(最多 2 层)
- 使用不一致的命名
- 忘记身份验证
- 返回敏感数据
- 在不版本化的情况下破坏向后兼容性