Restful-API设计最佳实战–Django播客系统(五)
文章目录
- Restful-API设计最佳实战--Django播客系统(五)
- RESTFul
- 1.协议
- 2.HTTP方法
- 3.使用名称
- 4.集合功能
- 5.状态码
- 6.错误处理
- 7.版本
- 8. 返回结果
RESTFul
- REST(Representational State Transfer),表现层状态转移。
- 它首次出现在2000年Roy Fielding的博士论文中,Roy Fielding是HTTP规范的主要编写者之一。
- 表现层是资源的表现层,对于网络中的资源就需要URI(Uniform Resource Identifier)来指向。
1.协议
- 使用HTTP或者HTTPS。对外若有安全性要求,可以使用HTTPS。但是内部服务间调用可以使用HTTP或HTTPS。
2.HTTP方法
- HTTP请求中的方法表示执行的动作
常用方法(动词) | 说明 |
GET | 获取资源 |
POST | 创建新的资源 |
PUT | 更新资源 |
PATCH | 部分更新资源 |
DELETE | 删除资源 |
3.使用名称
URL指向资源,在URL路径的描述中,只需要出现名称,而不要出现动词。动词由HTTP方法提供。
不要单复数混用,建议名称使用复数。
Restful的核心是资源,URL应该指向资源,所以应该是使用名称表达式,而不是动词表达。
方法 | 路径 | 说明 |
GET | | 返回所有文章 |
GET | | 返回id为10的文章 |
POST | | 创建新的文章 |
PUT | | 更新id为10的文章 |
DELETE | | 删除id为10的文章 |
PATCH | | 部分更新id为10的文章数据 |
- 不要出现如下的访问路径
/getAllPosts
/addPost
/updatePost
/delPost
- GET方法只是获取资源,而不是改变资源状态。改变资源请使用POST,PUT,DELETE等方法。
- 例如:使用
就可以获取资源了,但是却使用GET /posts/10
或Get /posts/10/del
,本意是想删除。但这样不好,GET方法请求只为获取资源,不要改变资源状态。GET /posts/10?v=del
- 子资源的访问
方法 | 路径Endpoint | 说明 |
GET | | 返回id为10的文章的所有作者 |
GET | | 返回id为10的文章的作者中id为4的 |
4.集合功能
- 过滤Filtering
- 指定过滤条件
GET /posts?tag=python
- 排序Sorting
- 指定排序条件。有很多种设计风格,例如使用
表示asc,+
表示desc。-
获取GET /posts?sort=+title,-id
GET /posts?sort=title_asc,id_desc
- 分页Pagination
- 一般情况下,查询返回的记录数非常多,必须分页。
GET /posts?page=58&size=20
5.状态码
- 使用HTTP响应的状态码表示动作的成功与否。
- 2xx表示用户请求服务端成功的处理;4xx表示用户请求的错误;5xx表示服务器端出错了。
Status Code | 说明 | Method | 说明 |
200 | OK | GET | 成功获取资源 |
201 | CREATED | POST,PUT,PATCH | 成功创建或修改 |
204 | NO CONTENT | DELETE | 成功删除资源 |
400 | Bad Request | ALL | 请求中有错误,例如:GET时参数有问题,PUT时提交的数据错误等 |
401 | Unauthorized | ALL | 权限未通过认证 |
403 | Forbidden | ALL | 有无权限都禁止访问该资源 |
404 | Forbidden | ALL | 请求资源不存在 |
500 | internal Server Error | ALL | 服务器端错误 |
- 详细状态码参考https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
6.错误处理
- 在Restful API设计中,错误处理也非常重要。单单从无状态码中无法详尽描述错误的信息。
- 返回消息
{error:"user NOT Found"}
- 从错误消息中了解到错误号、错误信息、错误描述等信息。甚至更详细的信息可以通过code查阅文档
{
"code":10056,
"message":"Invalid ID",
"description":"More details"
}
7.版本
- 强烈要求使用版本、版本号使用简单数字,例如v2。
- 2种风格
-
这种风格会跨域,适合较大的项目http://api.xdd.com/v1/posts/10
-
http://www.xdd.com/api/v1/posts/10
8. 返回结果
方法 | 路径 | 说明 |
GET | /posts | 返回所有文章的列表 |
GET | /posts/10 | 返回id为10的文章对象 |
POST | /posts | 创建更新的文章并返回这个对象 |
PUT | /posts/10 | 更新id为10的文章并返回这个对象 |
DELETE | /posts/10 | 删除id为10的文章返回一个空对象 |
PATCH |
- 数据一律采用JSON格式