RESTFul API

Representional State Transfer:表述性状态转移

本身来说概念非常抽象，从字面上都不能很好理解。不需要深层次了解对于开发工程师来说我们不用彻底了解rest是什么的，我们需要学会Restful的API设计，其本质可以认为是一种风格，一种约束，设计理念。

与之对应的有Soap其本身是相对重量级的，而目前互联网的发展是向轻量级的，其用XML来描述数据的，rest是通过json来描述数据的。从直观上来看，看json也更加可读些。

在soap出现之前js都不会直接访问服务器接口。WEB分为三部分，前段代码JS，后端代码，第三部分一个公共的服务。我们不提倡JS访问公共服务，因为浏览器有跨域限制，公共服务和网站不是在同一个域里，JS不能访问。服务形式为soap，其会生成代理类，代理类是在后台的，如果想用JS代码来调用公共服务，必须访问网站后台代码,，由后台代码来使用公共服务的代理类来访问公共服务。流程很长，显得很重。

Rest提供给我们更加轻量化的方式。目前大多数主流互联网产品都会优先使用Rest。Rest本身是一个基本的思想和理论，用Rest的理念设计出，具有Restful风格的API。RestFulAPI是Rest在web中的一种应用和延伸。Restful特点是轻，用JSON描述数据。另外其表现为无状态，即两个HTTP请求没有任何关系。另外，其所有的借口都是基于资源，所有的改变都是基于资源状态的改变。很多WEB框架都是把REST直接称之为资源，比如TP5提供Rest控制器就将其叫做资源控制器。REST表示资源的方法就是使用URL，所以REST一般不再URL里出现动词，只有名词。REST服务中使用HTTP动词来操作资源，用HTTP动词来描述资源的增删改查，比如GET，POST，PUT，DELETE…传统HTTP中，即使不了解REST服务，这些动词也是用的很多的，两者从技术上来讲没有区别。从意义上来讲，是有区别的。

传统：对资源的选择不是根据增删改查。比如用GET删除数据…

REST：GET表示查询，不可对删除使用GET，语义不明确

又例如/getmovie/:mid 不建议这么做没有动词操作，应该用GET：/movie/:mid

 

关于最佳实践，HTTP动词如下：

POST创建   PUT更新 GET查询        DELETE删除

其具有幂等性和资源安全性

 

对于HTTP相应的请求都要指明一个状态码，但是即使不去任何操作，每一个HTTP都自动携带状态码。比如说对GET操作，不去设置会自动设成200，POST则是201，一般是框架来设定的。

RESTFUL常用状态码：404资源没找到，400参数错误，200 GET请求执行成功，201POST创建资源成功，202PUT跟新成功，401未授权，403资源被禁止，500服务器未知错误

但也不一定，因为其没有很标准的规范，比如202在HTTP请求本身的状态码解释中202表示请求已经发送但是服务器没有处理，所以有些API把202设置成负责跟新成功的状态码比如豆瓣，有些则会吧POST和PUT成功都设置成201。

403特别需要提一下，本身是本来有权限访问这个资源，但是由于特殊原因不让访问这个资源所以设置成403，另外需要注意的是:假如我是A用户，又有一个B用户，由于我们都是API下面的用户，在我们身份认证的时候传入自己的账号密码，肯定能认证通过。加入要去调用一个接口，这个接口的参数指明这个借口需要操作哪个用户的数据，发生如下情况，我用我自己的身份，但是传入的是B id号如果不去做判断的话就会出现A用户操作B用户的数据，这时应该返回403!

500则是2种情况，第一种是确实不知道代码哪里有问题，未知BUG，不知道错误原因没办法返回具体的状态码，设置成500。第二种则是我知道错误的原因，但是由于服务器的原因和客户端没关系，并不想让客户端知道，所以设置成500.

错误码：自定义的错误ID，其是对错误的标识

统一描述错误：当客户端发生错误时，需要具体告诉客户端错误的信息这个信息用3个东西来定义：错误码，错误信息（这只是个简单的错误描述，但是用户可以通过错误码去文档中查看错误信息的），当前URL（表示出这个错误是访问哪个接口信息），也可以超过此三个添加自己的错误信息。

 

使用Token令牌来授权和验证身份，传统在网站用Cookie和Session来传递和保存用户的身份信息，但是在API中是需要用Token令牌的。Cookie和Token在本质上没有太大区别，但是在实现机制是有区别的。Cookie 是浏览器行为，每次访问时浏览器自动携带Cookie，

Token实现机制和Cookie差不多但是Token更多使我们自己存储管理的，所以Token更加灵活一下。

         版本控制：API一定要有版本号。不一定要在URL路径在，可以再hearder加也可以在 url参数加。不过我认为放到路径好一些。

         测试与生产环境分开：不仅仅是部署不同的站点，更重要的是把这两个站点用不同的域名表示，生产环境则是api.XXX.com是api的经典域名模式，开发版本前面加一个dev。

         RESTFulAPI设计一定要语义明确，最好望文知意，另外最好有一份比较标准的文档。

 

        学习RESTFulapi的最佳方式就是：模仿。两个开放API：豆瓣API https://developers.douban.com/wiki/?title=api_v2，推荐才入门RSETAPI的学习模仿。另外是GITHUB开发者API https://developer.github.com/v4/。

         最后，另外切勿盲目照搬标准REST，因为标准REST在内部开发真的不好用，因为其是基于资源的。比如两个不同类型的查询请求，可以设计成两个接口，设计成一个接口就特别复杂，还得设置标注类，特别的繁琐，客户端还看不懂。