A_78_RESTful

RESTful

特性理解

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）：从服务器删除资源。

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