【博客260】RESTFUL API--REpresentational State Transfer

内容： 记录一种API设计理论–RESTFUL

REST含义

REST是设计风格而不是标准。是指客户端和服务器的交互形式

RESTFUL API含义：

字面意义：RESTful API就是REST风格的API

实际概念：用http动作来操作URL资源

关键词：

     Resource：资源，即数据。
     Representational：某种表现形式，比如用JSON，XML，JPEG等；
     State Transfer：状态变化。通过HTTP动词实现。

调用关系：

RESTful API由后台也就是SERVER来提供前端来调用。前端调用API向后台发起HTTP请求，后台响应请求
将处理结果反馈给前端。也就是说RESTful 是典型的基于HTTP的协议。

设计原则与规范：

     1、资源。首先是弄清楚资源的概念。资源就是网络上的一个实体，一段文本，一张图片或者一首歌曲。
     资源总是要通过一种载体来反应它的内容。文本可以用TXT，也可以用HTML或者XML、图片可以用JPG
     格式或者PNG格式，JSON是现在最常用的资源表现形式。
    
    （注意：需要保证所有事物都可以被抽象为资源，且每一个资源都有唯一的资源标识，对资源的操作不会
      改变这些标识。）

    （注意：RESTFUL API基于http，所以安全性不高）

     2、统一接口。RESTful风格数据元操CRUD（create,read,update,delete）分别对应HTTP方法：
     GET用来获取资源；
     POST用来新建资源（也可以用于更新资源）；
     PUT用来更新资源；
     DELETE用来删除资源；

     3、URI。可以用一个URI（统一资源定位符）指向资源，即每个URI都对应一个特定的资源。要获取此
     资源访问它的URI就可以，因此URI就成了每一个资源的地址或识别符。一般的，每个资源至少有一个
     URI与之对应，最典型的URI就是URL

     4、无状态。所谓无状态即所有的资源都可以URI定位，而且这个定位与其他资源无关，也不会因为其它
     资源的变化而变化。有状态和无状态的区别
	
	举例：
		个人查询驾照考试结果，那么是需要先输入账号密码登录，然后登录后再进入个人中心，找到成绩
		查询按钮，按下查询。这里的每一步都依赖上一步，上一步执行失败则无法进入下一步。


     5、最好将API的版本号放入URL
   
     6、URL中只能有名词而不能有动词，操作的表达是使用HTTP的动词GET,POST,PUT,DELETEL。
     URL只标识资源的地址，不包括操作

     7、如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。
     比如：
		
	 查询可以捎带以下参数：
	 
     过滤条件：?type=1&age=16	
	 排序：?sort=age,desc	 
	 分页：?limit=10&offset=3
	 ...

	 8、URL的层次设计最好不要嵌套太多层

	 9、常见开头：api和version
	
	    将api部署在专门的域名下，比如：http://api.example.com
        将api放在主域名下，比如：http://www.example.com/api/
        
        将api的版本号放在url中，比如：http://www.example.com/api/v1.0

RESTFUL API举例：

查询驾照成绩：GET:http://www.xxx.com/grade/id   

驾照成绩有误，工作人员进行修改：POST:http://www.xxx.com/grade/id

数据安全性和幂等性：

数据安全性：是否对服务器后台数据造成影响

幂等性：执行一次和执行N次对资源的修改效果是否一致

操作的数据安全和幂等性：

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

常见HTTP返回状态码：

HTTP状态码-响应
服务器向用户返回的状态码和提示信息，使用标准HTTP状态码。

200：服务器成功返回用户请求的数据(get)，该操作是幂等的。(查)

201：新建或修改数据成功(post put path)。(增、改)

204：删除数据成功(delete)。(删)

400：语义有误，当前请求无法被服务器理解、请求参数有误

401：请求语法正确但是用户没有认证，无法进行当前操作。(无认证、无权限)

403：(用户提供了认证参数，但是参数错误、权限不足)表示服务器拒绝请求，用户访问是被禁止的。

404：请求资源不存在

422： (新建的用户的属性有遗漏、或格式错误)当创建一个对象时，发生一个验证错误。

500： 服务器发生错误，用户将无法判断发出的请求是否成功。

相应结果：

服务器向客户端返回的结果应符合规范，比如：

#返回查询对象列表
GET    http://www.XX.com/YY
#返回单个对象
GET    http://www.XX.com/YY/ZZ
#返回新生成的对象
POST   http://www.XX.com/YY
#返回一个空文档
DELETE http://www.XX.com/YY

与以往设计的对比：

RESTFUL API：

查询房间信息：GET http://XX.com/v1/room/id
删除房间信息：DELETE http://XX.com/v1/room/id
提交新房间信息：POST http://XX.com/v1/room/id

旧设计API：

查询房间信息：http://XX.com/check/room/id
删除房间信息：http://XX.com/room/delete/id
提交新房间信息：http://XX.com/room/id/method=post

对比：RESTFUL API非常规范也易于理解，而旧设计无统一规范，则非常的混乱

优点：

1.适合开放性高的API，提供一种统一的机制来规范API设计，使得API适用于各种各样的前端设备，
   REST符合这种需求。

2.行为和资源分离，更容易理解和管理

3.提出使用版本号（例如v1、v2），更加规范。