API 端点设计思想
- 简短便于输入
- 人可以读懂
- 没有大小写混用
- 修改方便
- 不会暴露服务器端架构的 URI
- 规则统一 URI
HTTP 方法
| 方法名 | 说明 |
|---|---|
| GET | 获取资源 |
| POST | 新增资源 |
| PUT | 更新已有资源 |
| DELETE | 删除资源 |
| PATCH | 更新部分资源 |
| HEAD | 获取资源元信息 |
API 端点设计
| 目的 | 端点 | 方法 |
|---|---|---|
| 获取用户信息列表 | http://api.example.com/v1/users | GET |
| 新用户注册 | http://api.example.com/v1/users | POST |
| 获取特定用户信息 | http://api.example.com/v1/users/:id | GET |
| 更新用户信息 | http://api.example.com/v1/users/:id | PUT/POST |
| 删除用户信息 | http://api.example.com/v1/users/:id | DELETE |
以上 5 个 API，但端点数量只有 2 个。
举例：
| 目的 | 端点 | 方法 |
|---|---|---|
| 获取用户的好友列表 | http://api.example.com/v1/users/:id/friends | GET |
| 添加好友 | http://api.example.com/v1/users/:id/friends | POST |
| 删除好友 | http://api.example.com/v1/users/:id/friends/:id | DELETE |
注意：URI 中如果出现不能直接使用的字符，会自动转换成百分号编码，例如空格、日语字符等，会出现%E3%81%82 等。
遇到这种情况需要遵循规范：连字符、占位符、驼峰法等。
- user_time
- user-time
- userTime
- user.time
google 规范是连字符，对 SEO 友好。
参考资料 《Web API 的设计与开发》 - 日水野贵明
补充说明：上面这本书讲了很多方面，包括版本迭代、错误的返回值和提示信息等。此部分没有应用到毕设中去，引用一篇博文作为补充。
学习设计 API -- 系统架构 -- IT 技术博客大学习