Restful API的设计与实践
Restful这个名称应该很多人都不陌生,但是我发现不少人对Restful存在或多或少的理解偏差,其中不泛比较厉害的程序员,所以有必要为Restful来“正名”。
Restful是一种软件架构风格,设计风格而不是标准,只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制。(详见百度百科介绍)
Restful的关键是抽取资源,使用URL与资源进行对应。这边也是多数人理解有偏差之处,即Restful应该理解为面向资源的架构风格,URL的设计应该是从资源的角度出发,而不应有任何的“动作”设计,其中单个资源共享同一个接口,而不同的“动作”通过请求的方法进行区分。这也是和RPC调用方式或RPC-Restful混合调用方式最大的不同之处。
那么为什么要使用Restful风格?有什么优势?
1、统一接口:约定大于配置,有了统一的规范,大家在接口设计时能够保证理解的一致性,这样首先便于接口的理解。另外同一资源URL一致,不同的CURD操作通过不同的Http协议方法进行区分,这样在设计上做到了简化。统一接口还有个非常容易被忽视的好处,就是方便使用Http协议自带的缓存机制对请求进行缓存操作,这样在一定程度上又提高了请求的性能。
2、无状态性:由于使用Http协议进行调用,每个请求都包含了服务器所需的全部信息,所以这种方式非常适用于异构系统之间的调用,同时也良好地支持分布式架构,可以动态地扩展服务器。这也是一个非常明显的优势。
Restful风格非常好,具体如何设计?
1、提取资源: 这一步非常关键,也是Restful的核心思想所在。在面向对象的世界里,对于资源的识别不算太难,一般情况下资源即是想要处理的对象,如果对应到表结构上面,可能就是表对应的实体。例如电子商务网站上的下订单,那资源就是订单;如果是商品展示,那资源就是商品。当然这是最简单的情况,如果稍微复杂一点,比如现在是家电类的商品展示怎么办呢?那资源就是商品-家电类。像上面所述的情况,资源比较好识别,而有些情况下资源就不是那么明显了,比如登录,这是哪门子资源?这种情况确实不太好抽象,不过可以理解为登录信息资源。登录操作是对登录信息资源的新增操作。还有其它更复杂的情况,这个就得发挥面向资源的思路做进一步的抽象了。
2、URI设计: URI的设计其实与资源提取紧密相关,基本只要资源提取出来了,URI只是相应地翻译成地址就可以,有层级的资源通过分隔符进行路径区分。例如上面提到的商品展示可以是/goods,家电类商品可以/goods/elecequipt/,而登录可以是/loginInfo。
3、具体的动作: 这个严格说来并不是设计的一部分,是属于规范的一部分。因为使用Http协议,而协议中正好有相应的方法支持,所以正好使用Http协议的方法。(1)GET:获取资源的方法;(2)PUT:更新资源的方法;(3)POST:创建资源的方法;(4)DELETE:删除资源的方法。这几个 是比较常用的,还有几个不太常用的方法:(5)OPTIONS:查看资源支持哪些方法;(6)HEAD:与PUT类似,只不过HEAD只返回报头,不返回表示。
这里需要着重提一下,很多Restful-RPC混合模式可能就只会使用POST方法,这里就是混合模式与Restful风格最明显的区别之一。
4、返回结果: 返回结果包括Http请求的状态码和资源的表述。很多情况下API的返回结果使用Json或者XML格式表示,而Json是更加常用的。因为Json相比XML更加轻量,这样在传输过程中资源更小传输更快,另外Json的解析支持更广,所以解析起来非常方便。
5、缓存: Http协议是天然支持缓存的,这个也有利于性能的提升。当然服务端也可以添加缓存提高性能,这是另一个话题。缓存具体的实现在Http Header里面进行设置,例如Cache-Control、Expires。具体用法可以参见协议头描述:http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
6、安全性: 如果资源是公开的,那也没有什么安全性可言了。但是实际情况是很多资源是有对应的“权限”进行操作的,这个时候就需要进行身份的认证,认证才能够进行相应的操作。所以安全性也是设计中很重要的一环。
那么安全性如何保证呢?在Http协议中有Authorization头可以进行相关设置,最基本的可以使用Basic方式,更加安全的加密方式使用Digest方式,更进一步提高安全性还可以使用第三方的OAuth协议进行认证,OAuth也是经常采用的方式。具体使用可参考网上看到的一篇非常好的博文:理解OAuth2.0。另外为了安全性的保证,大多数情况下还会选用https协议进行传输。
设计的思路有了,那么该如何付诸实践?
1、使用场景: 前面也提到了,Restful风格特别适合于异构系统之间的调用,另外在分布式场景中也比较适用。比如现在移动端APP的接口设计很多都采用这种风格,另外有不少云平台提供的服务接口也大多采用Restful风格设计。使用还是比较广泛的。
2、实践示例: 说了半天理论还是略显空洞,下面直接来点示例加深下理解。限于篇幅,这里推荐几个看到的比较好的例子。
简单情况下的使用示例可以参考网上看到的一篇非常好的博文:理解Restful架构。
稍微复杂一点的情况可以考虑现在比较知名的云平台的API设计,比如百度云推送API设计:http://push.baidu.com/doc/restapi/restapi。另外还推荐一个看到的Saas服务商的Restful设计文档,写得很好,环信的聊天API设计:http://docs.easemob.com/doku.php?id=start:100serverintegration。
这边有几个有意思的地方可以特别关注下,比如API中的安全认证设计、接口输入输出设计。另外如果看得仔细,可能会注意到百度云平台推送平台的API设计可能与前面提到的Restful本身的设计思路有些出入,百度云推送的设计方式严格说来应该算是Restful-Rpc混合模式的设计。不过也不影响做为参考。
3、框架支持: 这里以Java版本的为例。Java对于Restful有一个规范定义JAX-RS,而支持Restful框架也不少,比如:Restlet、Jersey、RESTEasy、CXF。这几个框架的比较可以参考这篇博文:http://www.infoq.com/cn/news/2008/10/jaxrs-comparison/。我对Restlet和Jersey进行了简单了解,没有做深入的使用,觉得Restlet的文档是做得更好的。
除了上面提到的框架,现在非常流行的Spring MVC框架也对Restful有良好的支持,比如可以参考这篇的实践:http://www.importnew.com/7903.html,Spring框架的支持还是非常不错的。
参考资料
1、《RESTful Java with JAX-RS 2.0》
2、《RESTful Web APIs》
3、《RESTful Web Services Cookbook》中文版
4、《RESTful Web Services》中文版
5、《REST实战》中文版
Restful API的设计与实践的更多相关文章
- atitit.基于http json api 接口设计 最佳实践 总结o7
atitit.基于http json api 接口设计 最佳实践 总结o7 1. 需求:::服务器and android 端接口通讯 2 2. 接口开发的要点 2 2.1. 普通参数 meth,p ...
- 好RESTful API的设计原则
说在前面,这篇文章是无意中发现的,因为感觉写的很好,所以翻译了一下.由于英文水平有限,难免有出错的地方,请看官理解一下.翻译和校正文章花了我大约2周的业余时间,如有人愿意转载请注明出处,谢谢^_^ P ...
- RESTful API的设计原则
好RESTful API的设计原则 说在前面,这篇文章是无意中发现的,因为感觉写的很好,所以翻译了一下.由于英文水平有限,难免有出错的地方,请看官理解一下.翻译和校正文章花了我大约2周的业余时间, ...
- 好的RESTful API的设计原则
转载自一位大佬 英文原版 Principles of good RESTful API Design Good API design is hard! An API represents a cont ...
- [Medium翻译]RESTful API权威设计指南-设计更好的API
本文为授权译文.希望查看原文的同学请戳链接:https://hackernoon.com/restful-api-design-step-by-step-guide-2f2c9f9fcdbf 对于我们 ...
- RESTful API URI 设计: 查询(Query)和标识(Identify)
相关文章:RESTful API URI 设计的一些总结. 问题场景:删除一个资源(Resources),URI 该如何设计? 应用示例:删除名称为 iPhone 6 的产品. 是不是感觉很简单呢?根 ...
- RESTful API URI 设计: 判断资源是否存在?
相关的一篇文章:RESTful API URI 设计的一些总结. 问题场景:判断一个资源(Resources)是否存在,URI 该如何设计? 应用示例:判断 id 为 1 用户下,名称为 window ...
- [转]10个有关RESTful API良好设计的最佳实践
Web API已经在最近几年变成重要的话题,一个干净的API设计对于后端系统是非常重要的. 通常我们为Web API使用RESTful设计,REST概念分离了API结构和逻辑资源,通过Http方法GE ...
- 10个有关RESTful API良好设计的最佳实践
Web API已经在最近几年变成重要的话题,一个干净的API设计对于后端系统是非常重要的. 通常我们为Web API使用RESTful设计,REST概念分离了API结构和逻辑资源,通过Http方法GE ...
随机推荐
- 大白话系列之C#委托与事件讲解(一)
从序言中,大家应该对委托和事件的重要性有点了解了吧,虽然说我们现在还是能模糊,但是从我的大白话系列中,我会把这些概念说的通俗易懂的.首先,我们还是先说说委托吧,从字面上理解,只要是中国人应该都知道这个 ...
- Java_数组
一.java数组 1.数组定义:数组就是形象于一个容器(容器即可理解为:装东西的容器) 2.数组特征:数据是连续的,分配大小固定,数组中数据类型完全一致 创建规则:int[] arr = new in ...
- JavaOOP 试题
1) 以下属于OOP的特征有(). a)继承 b)封装 c)多态 d)隐藏 2) JavaOOP中的多态包括() a) 方法重写 b) 方法重载 c) 方法隐藏 d) 以上 ...
- mfs-管理员
http://www.moosefs.org/http://moosefs.com/download.html 两个手册于2015/03/05阅完 moosefs-installation moose ...
- alpha预乘
将(r,g,b,a)变为(r*a,g*a,b*a,a)的操作称为alpha预乘. 对于alpha预乘的图片,应使用(One,OneMinusSrcAlpha)进行混合. 使用alpha预乘方式混合出来 ...
- html之内联标签a
a标签:定义超链接,用于从一个页面链接到另一个页面,最重要的属性href,如果没有href属性,则不可以使用如下属性:download,hreflang,media,rel,target,type. ...
- Android软键盘遮挡的四种解决方案
问题概述 在编辑框输入内容时会弹出软键盘,而手机屏幕区域有限往往会遮住输入界面,我们先看一下问题效果图: 输入用户名和密码时,系统会弹出键盘,造成系统键盘会挡住文本框的问题,如图所示: 输入密码时输入 ...
- ExtJs学习笔记之TextField
输入框TextField 一个基本文本框表单项.可以直接代替传统文本输入框, 或者作为许多复杂基本控件的基类({如@link Ext.form.field.TextArea}) 和Ext.form.f ...
- oracle中where 子句和having子句中的区别
1.where 不能放在GROUP BY 后面 2.HAVING 是跟GROUP BY 连在一起用的,放在GROUP BY 后面,此时的作用相当于WHERE 3.WHERE 后面的条件中不能有聚集函数 ...
- httpClenit的post出现乱码问题
在使用httpClient.executeMethod(postMethod)的时候,发现一直存在乱码问题,”book is good“被转成”book+is+good“ 返回.查看源码后,发现pos ...