A_78_RESTful
2021-04-15 22:54:50 0 举报AI智能生成
全面、高效的知识图谱：A_78_RESTful!! 全面又深度的提升认知，达到实际应用的目的! 建议先纵观全局，掌握好大方向。 再根据自己的需要，针对性的学习某一个点，最后做到逐步由点及面。
作者其他创作
大纲/内容
特性理解
HTTP协议，是一个无状态协议
因多次http请求间,http不提供公共存储介质.所以,多次htt请求间没有业务数据(业务状态,称无状态)的记忆能力
cookie,session在http协议外,浏览器提供的多次http请求中,公共的存储介质.即在多次http间共享了业务数据(业务状态,称有状态)
幂等的（Idempotent）
幂等性意味着对于一个成功执行的请求，不管其执行多少次，其结果都是一致的
或表示为:是否可以重复执行,且不影响业务或不改变数据
get
是
常用于:查
当操作没有达到预期的目标时，我们可以不停的重试，而不会对资源产生副作用
delete
是
常用于:删
同上
put
是
常用于:更新
同上
post
不是
常用于:新增
当操作没有达到预期的目标时，不可重试,新增操作(非幂等)会出现多条资源记录
辩论
具体的程序逻辑里面，完全可以把POST动作实现为幂等操作，比如POST /user 创建新用户，POST /user/1 修改id为1的用户信息，无论POST /user/1多少次，都是对id为1的用户进行修改（幂等）。
真正的理由是，REST仅仅是一种架构风格的指导规范，并非具体技术实现。因此用POST新建，PUT修改仅仅是具体实施过程中的约定。就像代码需要合理的缩进一样，虽然不缩进，程序也能执行（python除外），但安装这个约定去做，事情可以做得更漂亮点。
我也看到过其它的REST文章建议说POST修改，PUT新建，我更倾向于POST新建，PUT修改。
没错，你是可以把post /users/1 实现为幂等的。但是通用客户端，比如浏览器，没有这样的预先假设。当post 操作异常时，比如超时，服务器503等等，浏览器是不能自动重试post操作的。这样你的幂等的 post /users/1 并没有给你带来太多的好处，除非你的客户端都是定制客户端 REST确实不是技术标准，但是HTTP是标准。
基于幂等性的解决方案
任何一步由于网络等原因失败或超时，客户端都可以重试，直到获得结果。
RESTful客户端-$resource
分支主题
分支主题
参考
理解RESTful架构-阮一峰
RESTful API 设计指南-阮一峰
如何理解HTTP协议的“无连接，无状态”特点？
developer.github.com API设计
从消费者的角度评估REST的价值 之 Hypermedia
Representational State Transfer
资源（Resources）
所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息
表现层（Representation）
"资源"是一种信息实体，它可以有多种外在表现形式。我们把"资源"具体呈现出来的形式，叫做它的"表现层"（Representation）
比如，文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式；图片可以用JPG格式表现，也可以用PNG格式表现
状态转化（State Transfer）
互联网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生"状态转化"（State Transfer）。而这种转化是建立在表现层之上的，所以就是"表现层状态转化"
客户端用到的手段，只能是HTTP协议。具体来说，就是HTTP协议里面，四个表示操作方式的动词：GET、POST、PUT、DELETE。
它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。
综述
（1）每一个URI代表一种资源；
（2）客户端和服务器之间，传递这种资源的某种表现层；
（3）客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。
注意事项
REST仅仅是一种架构风格的指导规范，并非具体技术实现
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应
HTTP动词
GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。
HTTP动词,示例
GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物
过滤信息（Filtering）
如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果
?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件
参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复
比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的
返回结果
GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档
Hypermedia API
RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么
比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档
Hypermedia API的设计被称为HATEOAS
api.github.com
api.github.com/user
其他
（1）API的身份认证应该使用OAuth 2.0框架。
（2）服务器返回的数据格式，应该尽量使用JSON，避免使用XML。
误区
最常见的一种设计错误，就是URI包含动词
举例来说，某个URI是/posts/show/1，其中show是动词，这个URI就设计错了，正确的写法应该是/posts/1，然后用GET方法表示show
资源不能是动词，但是可以是一种服务
错误 POST /accounts/1/transfer/500/to/2
正确 POST /transaction?from=1&to=2&amount=500.00
另一个设计误区，就是在URI中加入版本号
http://www.example.com/app/1.0/foo
http://www.example.com/app/1.1/foo
因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区分
Accept: vnd.example-com.foo+json; version=1.0
Accept: vnd.example-com.foo+json; version=1.1
0 条评论
下一页
