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 Identiﬁer)来指向。

1.协议

使用HTTP或者HTTPS。对外若有安全性要求，可以使用HTTPS。但是内部服务间调用可以使用HTTP或HTTPS。

2.HTTP方法

HTTP请求中的方法表示执行的动作

常用方法(动词)	说明
GET	获取资源
POST	创建新的资源
PUT	更新资源
PATCH	部分更新资源
DELETE	删除资源

3.使用名称

URL指向资源，在URL路径的描述中，只需要出现名称，而不要出现动词。动词由HTTP方法提供。
不要单复数混用，建议名称使用复数。
Restful的核心是资源，URL应该指向资源，所以应该是使用名称表达式，而不是动词表达。

方法	路径	说明
GET	`/posts`	返回所有文章
GET	`/posts/10`	返回id为10的文章
POST	`/posts`	创建新的文章
PUT	`/posts/10`	更新id为10的文章
DELETE	`/posts/10`	删除id为10的文章
PATCH	`/posts/10`	部分更新id为10的文章数据

不要出现如下的访问路径

/getAllPosts
/addPost
/updatePost
/delPost

GET方法只是获取资源，而不是改变资源状态。改变资源请使用POST,PUT,DELETE等方法。
例如：使用GET /posts/10就可以获取资源了，但是却使用Get /posts/10/del或GET /posts/10?v=del,本意是想删除。但这样不好，GET方法请求只为获取资源，不要改变资源状态。
子资源的访问

方法	路径Endpoint	说明
GET	`/posts/10/authors`	返回id为10的文章的所有作者
GET	`/posts/10/authors/8`	返回id为10的文章的作者中id为4的

4.集合功能

过滤Filtering
1. 指定过滤条件GET /posts?tag=python
排序Sorting
1. 指定排序条件。有很多种设计风格，例如使用+表示asc,-表示desc。GET /posts?sort=+title,-id获取GET /posts?sort=title_asc,id_desc
分页Pagination
1. 一般情况下，查询返回的记录数非常多，必须分页。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种风格
1. http://api.xdd.com/v1/posts/10 这种风格会跨域，适合较大的项目
2. 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	/posts/10	部分更新id为10的文章数据并返回这个对象

数据一律采用JSON格式

Restful-API设计最佳实战--Django播客系统(五)相关推荐

[译] RESTful API 设计最佳实践
https://juejin.im/entry/6844903503953920007 [译] RESTful API 设计最佳实践阅读 8779 收藏 0 2017-10-16 原文链接: seg ...
用户功能设计与实现--Django播客系统(六)
用户功能设计与实现–Django播客系统(六) 文章目录用户功能设计与实现--Django播客系统(六) 用户注册接口设计路由配置测试JSON数据 CSRF处理 JSON数据处理错误处理注册 ...
RESTful API 设计最佳实践
2019独角兽企业重金招聘Python工程师标准>>> 背景目前互联网上充斥着大量的关于RESTful API(为方便,下文中"RESTful API "简写为 ...
RESTful API设计技巧经验总结
原文:RESTful API Design Tips from Experience 作者:Peter Boyer 翻译:雁惊寒译者注:本文是作者在自己的工作经验中总结出来的RESTful API设 ...
RESTful架构和RESTful API设计总结
作者:智明书链接:https://www.jianshu.com/p/955eb2faa354 REST这个词是2000年Roy Fielding在他的博士论文中提出的,Fielding参与了htt ...
RESTful API 设计指南 (转)
RESTful API 设计指南 2016-02-23 ImportNew (点击上方公号,可快速关注) 作者:阮一峰链接:http://www.ruanyifeng.com/blog/2014/0 ...
从英文变形规则计算到Restful Api设计
➠更多技术干货请戳:听云博客一天在研究Restful API设计,命名的时候我总是很纠结,我相信大多数人也有这种感觉,不是说想不出来某个单词怎么写的问题,像我这种没事背单词背到13000词量的人也要 ...
我是如何根据豆瓣api来理解Restful API设计的
1.什么是REST REST全称是Representational State Transfer,表述状态转移的意思.它是在Roy Fielding博士论文首次提出.REST本身没有创造新的技术.组件 ...
RESTful API 设计指南[转]
一种软件架构风格.设计风格,而不是标准,只是提供了一组设计原则和约束条件.它主要用于客户端和服务器交互类的软件.基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制. RESTful AP ...

Restful-API设计最佳实战--Django播客系统(五)

Restful-API设计最佳实战–Django播客系统(五)

文章目录

RESTFul

1.协议

2.HTTP方法

3.使用名称

4.集合功能

5.状态码

6.错误处理

7.版本

8. 返回结果

Restful-API设计最佳实战--Django播客系统(五)相关推荐

最新文章

热门文章