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在内部开发真的不好用,因为其是基于资源的。比如两个不同类型的查询请求,可以设计成两个接口,设计成一个接口就特别复杂,还得设置标注类,特别的繁琐,客户端还看不懂。

阅读更多
换一批

没有更多推荐了,返回首页