可靠且易于理解的API从构建接口的明确规则开始。我们遵循REST最佳实践,以确保每个开发人员都知道会发生什么：URL结构是合乎逻辑的,方法对应于操作,错误易于解释。
这降低了登录阈值，简化了集成，并允许在没有混乱的情况下扩展系统。
URL和HTTP方法约定
| 方法 | 指定 | 查询示例 |
|---|---|---|
| `GET` | 获取资源 | `GET /users/42` |
| `POST` | 创建新资源 | `POST /users` |
| `PUT` | 完全更新资源 | `PUT /users/42` |
| `PATCH` | 部分资源更新（opz.）`PATCH /users/42` | |
| `DELETE` | 删除资源 | `DELETE /users/42` |
使用复数形式的名词（"/users"，"/devices"，"/games"）
嵌套实体被描述为层次结构（'/users/42/sessions'）
所有查询均通过HTTPS进行
错误处理标准
| 代码 | 值为 | 示例消息 |
|---|---|---|
| `400` | 不正确的请求 | `Missing required field: email` |
| `401` | 未授权 | `Invalid token or expired session` |
| `403` | 禁止访问 | `Access denied to resource` |
| `404` | 未找到 | `User with ID 42 not found` |
| `409` | 冲突（例如重复） | `Email already in use` |
| `422` | 验证错误 | `Field 'age' must be a number` |
| `500` | 内部服务器错误 | `Unexpected exception, contact support` |
错误响应结构：
json
{
"error": {
"code": 400, "message": "Missing required field: email", "details": {...}
}
}对开发人员的好处
快速理解API逻辑而无需多余的文档
所有模块和实体的统一方法
通过标准代码和格式轻松调试和编写
与OpenAPI/Swagger、Postman、SDK自动生成兼容
简化支持、测试和CI/CD
在哪里，特别重要
开放或合作伙伴API平台
具有多个开发团队的项目
微服务体系结构或API第一方法
具有大量实体和交互的系统