对restful 理解

1. 什么是restful

    REST——Representational State Transfer，表现层状态转移。它被Roy Felding提出（在他的”基于网络的软件架构“论文中第五章）。REST的核心原则是将API拆分为逻辑上的资源。这些资源通过http被操作（GET ,POST,PUT,DELETE）。

    如果一个架构符合rest原则，就称它为restful架构。

    理解restful架构，首先要理解rest

• resources 资源是指网络上的一个实体，或者说一个具体信息。而表现层实际上就是资源的表现层
• representation 把”资源”具体呈现出来的形式，叫做它的”表现层”。

• state transfer 访问一个网站，一定涉及到客户端和服务端的交互，也就一定存在数据和状态的变化，这就是状态转化

  rest风格的特征

• 客户端服务端分离

• 无状态
• 缓存
• 分层部署
• 统一接口
• 支持按需代码

综述：什么是restful架构

• 每一个URI代表一种资源
• 客户端和服务器之间，传递这种资源的某种表现层
• 客户端通过http动词，对服务器端资源进行操作，实现“表现层状态转化”。
  （就是用URL定位资源，用HTTP描述操作。
      看Url就知道要什么
      看http method就知道干什么
      看http status code就知道结果如何）

2. restful 实例及误区

    restful 架构典型设计误区

• URI 包含动词
  /posts/show/1 X
  /posts/1 √
  使用get方法实现show

3. restful API设计规范

1. 协议
   API与用户的通信协议，总是使用HTTPs协议

2. 域名
   应该尽量将API部署在专用域名之下。
   如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

3. URI规范
   不用大写；
   用连字符’-’ 不用下划线 ‘_’ ；
   参数列表要encode；

4. HTTP动词

动词	说明
GET（SELECT）	从服务器取出资源（一项或多项）。
POST（CREATE）	在服务器新建一个资源。
PUT（UPDATE）	在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）	在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）	从服务器删除资源。
HEAD	获取资源的元数据。
OPTIONS	获取信息，关于资源的哪些属性是客户端可以改变的。

安全性和幂等性

安全性：不会改变资源状态，可以理解为只读的；
幂等性：执行1次和执行N次，对资源状态改变的效果是等价的。

方法	安全性	幂等性
GET	√	√
POST	×	×
PUT	×	√
DELETE	×	√

    安全性和幂等性均不保证反复请求能拿到相同的response。以 DELETE 为例，第一次DELETE返回200表示删除成功，第二次返回404提示资源不存在，这是允许的。
 
5. 错误处理
       不要发生了错误但给2xx响应，客户端可能会缓存成功的http请求；
       正确设置http状态码，不要自定义；
       提供 a. 错误的代码（日志/问题追查）；b. 错误的描述文本（展示给用户）

常用状态码

状态码	error	使用场景
200	OK	服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201	create - [POST/PUT/PATCH]	用户新建或修改数据成功。
202	accepted	表示一个请求已经进入后台排队（异步任务）
204	no conflict - [DELETE]	用户删除数据成功。
400	bad request	常用在参数校验
401	unauthorized	未经验证的用户，常见于未登录。
403	forbidden	无权限
404	not found	资源不存在
500	internal server error	非业务类异常
503	service unavaliable	由容器抛出，自己的代码不要抛这个异常

6. API的演进

常见的三种方式：

    在uri中放版本信息：GET /v1/users/1
    Accept Header：Accept: application/json+v1
    自定义 Header：X-Api-Version: 1
    用第一种，虽然没有那么优雅，但最明显最方便。

参考文章：
http://novoland.github.io/%E8%AE%BE%E8%AE%A1/2015/08/17/Restful%20API%20%E7%9A%84%E8%AE%BE%E8%AE%A1%E8%A7%84%E8%8C%83.html
http://www.ruanyifeng.com/blog/2011/09/restful.html
http://www.ruanyifeng.com/blog/2014/05/restful_api.html