再谈RestAPI最佳实践

标签: restapi 最佳实践 | 发表时间:2014-05-25 14:50 | 作者:mybreeze77
出处:http://www.iteye.com

本文翻译自 http://www.javacodegeeks.com/2014/05/rest-api-best-practices-reloaded.html ,仅供学习和参考,转载请注明出处。

 

近一年半,我参与了2到3个项目的工作,这些项目涉及到大量供“外部”使用的Rest API,稍后我们再来解释为什么要将“外部”这个词放在引号之中。在项目工作期间,我不得不对这些API进行反复地设计,再设计和重构,这篇文章是我对Rest API最佳实践的一些个人看法,希望读者能够从中获益。
 
更好、更早地设计
对于很多语言来说,实现Rest Service是一项极其微不足道的任务。换言之,无论你选择什么底层框架,只要辅以少量配置和代码,你可以在一小时之内就拥有一个Rest Service。虽然对于缺乏经验的人来说,这确实很方便,但它也很容易让你迅速写出一个质量低下的API。因此,在你编写代码之前,先留出一分钟的时间思考一下,试着去设计你的API,花足够的时间去理解业务范畴,判断客户端需要从你的系统中获取什么。举个例子,如果你的系统是针对一群硬币收藏家建立的数据库,此时你需要决定的是:你是否允许客户端添加新的硬币,或者仅仅允许取出原有的硬币;客户需要什么样的查询方式;如果遇上涉及大量数据检索的请求,你如何处理它?尽早地回答这些问题能够帮助你开发出更贴近用户需求的API。
 
名称与方法
现在已经很有多关于Resource命名和组织的讨论了,在这里我基于自己的经验再老调重弹一下,以下是三种应该遵循的规则。
1. 只使用名词:举个例子,如果你想提供一项在数据库中搜索硬币的服务,要避免将Endpoint命名为/searchCoins或/findCoins或/getAllCoins 等等,一个简单的/coins就已经足够了,当客户端发送一个GET请求的时候,可以获得所有有效硬币的集合。类似的,如果你想提供一项在数据库中添加硬币的服务,要避免使用诸如/addCoin或/saveCoin或/insertCointToDatabase这样的名称,你可以使用与上面相同的Rource名称,要改变的仅仅是用POST请求代替GET请求。同样地,对于更新硬币,可以使用PUT请求。

2. 如果需要获取单个硬币,又应该怎么做呢?我所建议的最佳方式是在Endpoint中加入一个参数,比如说客户端需要拿到一个ID是20的硬币,那么发送一个请求到/coins/20就足够了。我们再来看一个更复杂的例子,如果要让客户端能够为每个硬币添加一张图片,一个快速而丑陋的方式是/addCoinImage或/addNewImageToCoin等等。一个稍好一点的方式是/coins/addImage,但是正如我之前所说的,其中不应该有任何动词存在。还记得我们之前提到的获取某种硬币的方法吗?我们可以将其稍微加强一下,发送POST请求给/coins/20/images如何?目前看起来很不错。不过天下没有完美的事物,假设一下,如果我们要让一些超级用户能够从系统中删除硬币,根据我们之前的讨论,一个简单的DELETE请求发送给/coins/{id}就足够了,但是请你想一下,如果{id}仅仅是COINS表中的一个顺序编号,那会产生多大的问题?某人可以毫无压力地一个接一个的发送DELETE请求,最后系统中所有的数据全没了。我想说的重点是,使用标识符作为请求参数是不错,但是前提是这些标识符必须很难猜测或根本无法猜测。所以,如果你想要用一串序号去确定一个实体,那就忘了这种实现吧。我的建议是,不要使用Resource参数,直接发送一个DELETE请求给/coins,结合一个request body(比如json),其中拥有足够定位所要被删除的实体的参数,这就可以了。

3. 尽可能多的使用特定领域的名称。如果你的业务域中有一群硬币收藏家(Coin Collectors),那么当你设计API的时候,应当使用collectors这个词,而不是users或accounts。要避免使用一个意义过于宽泛的名称,这些名称不能代表什么,到了客户端又容易产生误解。对于请求参数的命名,道理也是一样的。另外,强烈建议给请求参数取一个尽可能短,同时又有意义的名称,举个例子,如果你想要查找在某一指定年份发行的硬币,一个很赞的参数名称是issueYear,比较典型的反例是:year(意义不明确),yearOfFirstIssue(包含无用信息)。
 
错误处理和响应
对于这个话题,我的经验是让客户端在每次发送请求后,都能获得相同格式的json响应,无论结果是成功还是失败,这将会给客户端处理带来极大的帮助。举个例子,你想要添加一个新的硬币,向/coins发送POST请求,一个成功的响应包含以下json文档:
 
{
     "meta":{
      "code":200
   },
   "data":{
      "coinId":"a7sad-123kk-223"
   }
}
 
一个错误的响应可能是这样的:
 
{
     "meta":{
      "code":60001,
      "error":"Can not add coin",
      "info":"Missing one ore more required fields"
   },
   "data":{
   }
}
 
请注意,对所有可能的结果(成功或失败),json响应的文档都具备相同的结构,其中有两种基本元素:meta和data,前者包含结果信息,在出错的情况下,其中还将包含一个特殊的error code,同时,"error"表示出错的内容,"info"表示出错的具体描述;后者(可选的)包含从服务器返回的所有数据,就拿上面的例子来说,当添加硬币成功后,服务器返回一个唯一的自动生成的标识符,如果有错误,这项就为空。这种做法的优势是,对于同一个API的各种服务类型和结果,客户端都可以采用相同的方式进行处理。此外,当有意外情况发生时,我们也可以传递一些额外的信息,正如上面例子中所展示的,"error"传达信息,"info"记录日志。还有一种选择,可以基于error code去处理响应,只要明确每个数字的含义即可,请记住这些数字并非http状态码,你依然要为每个请求返回正确的http状态码(如400、401等)。

在我们讨论下一节之前,我想强调另一个应该牢记的要事,假设我们不允许删除硬币,但是客户端尝试向/coins/{id}发送一个DELETE请求,通常情况下Web容器会返回一个405的状态码,但我发现,对这些响应进行过滤,返回相同的json文档,会很有帮助,比如我们可以返回:
 
{
     "meta":{
      "code":405,
      "error":"Method not allowed for the /coins/{id} resource",
      "info":"Method DELETE is not allowed for that resource. Available methods : GET, POST, OPTIONS"
   },
   "data":{
   }
}
 
这比原来好多了,不是吗?现在,响应内容不但包含原有的信息(405状态码),还通知客户端该Resource可用的方法。
 
文档
最后但也是最重要的一点,花一点时间,提供一份专业的、对开发人员友好的文档,并保证及时更新,一份过期文档的危害性比没有文档更甚。你可以使用一些开源免费的工具对你的API进行文档化。再好一点的做法是,对每一个Resource的使用方式都能提供范例,对成功或错误的响应能提供预期结果。不要忘了,在最后要记录下每一个error code并提供完整的信息,这样客户端才能在错误发生时做出反应,有一些客户端不会理会你的响应内容,它们会根据你的error code自行提供信息。


已有 0 人发表留言,猛击->> 这里<<-参与讨论


ITeye推荐



相关 [restapi 最佳实践] 推荐:

再谈RestAPI最佳实践

- - 企业架构 - ITeye博客
http://www.javacodegeeks.com/2014/05/rest-api-best-practices-reloaded.html ,仅供学习和参考,转载请注明出处. 近一年半,我参与了2到3个项目的工作,这些项目涉及到大量供“外部”使用的Rest API,稍后我们再来解释为什么要将“外部”这个词放在引号之中.

jQuery最佳实践

- andi - 阮一峰的网络日志
上周,我整理了《jQuery设计思想》. 那篇文章是一篇入门教程,从设计思想的角度,讲解"怎么使用jQuery". 今天的文章则是更进一步,讲解"如何用好jQuery". 我主要参考了Addy Osmani的PPT《提高jQuery性能的诀窍》(jQuery Proven Performance Tips And Tricks).

PHP最佳实践

- xiangqian - 阮一峰的网络日志
虽然名字叫《PHP最佳实践》,但是它主要谈的不是编程规则,而是PHP应用程序的合理架构. 它提供了一种逻辑和数据分离的架构模式,属于MVC模式的一种实践. 我觉得,这是很有参考价值的学习资料,类似的文章网上并不多,所以一边学习,一边就把它翻译了出来. 根据自己的理解,我总结了它的MVC模式的实现方式(详细解释见译文):.

MongoDB最佳实践

- - NoSQLFan
将 MongoDB加入到我们的服务支持列表中,是整个团队年初工作计划中的首要任务. 但我们感觉如果先添加一项对NoSQL存储的支持,而不是先升级已支持的关系型数据库,可能对用户不太好,毕竟目前的用户都使用关系型数据库. 所以我们决定将引入MongoDB这项工作放到升级MySQL和PostgreSQL之后来做.

文章: Grails最佳实践

- - InfoQ cn
我在IntelliGrape工作,这是一家专门使用Groovy & Grails进行开发的公司. 本文是我们Grails项目遵循的最佳实践的基本清单,收集自邮件列表、Stack Overflow、博文, 播客和 IntelliGrape的内部讨论. 它们分为控制器、服务、Domain、视图、TagLib、测试和其他.

PHP最佳实践(译)

- - CSDN博客Web前端推荐文章
原文:  PHP Best Practices-A short, practical guide for common and confusing PHP tasks. 译者: youngsterxyf. 本文档最后审阅于2013年3月8日. 由我, Alex Cabal,维护该文档. 我编写PHP程序已有很长一段时间了,当前我 经营着 Scribophile,由认真作家组成的一个在线写作团体,  Writerfolio,为自由职业者提供的一个易用写作工具集,以及  Standard Ebooks,一个图文并茂、无数字版权管理的公共领域电子书出版商.

Log4j最佳实践(原) - Mainz

- - 博客园_Mainz's Blog
本文是结合项目中使用 Log4j总结的最佳实践,非转载. 网上可以找到的是这一篇《 Log4j最佳实践》. 本来 Log4j使用是非常简单的,无需多介绍其用法,这只是在小型项目中;但在 大型的项目中使用 log4j不太一样. 大型项目非常依赖日志,因为解决线上问题必须依靠log,依靠大量的日志.

一些 REST 最佳实践

- - 鸟窝
原文: Some REST best practices, 作者: Pierre-Olivier Bourgeois. 译文: 一些REST最佳实践, 译者: yongx. 如今,REST APIs 已经非常普遍,几乎所有WEB应用都用到了它们. 提供简单,一致,实用的API是种义务,方便其它人很容易的使用.

Redis最佳实践 | kikoroc

- -
redis是一款开源的内存数据存储系统,可以用作数据库、缓存甚至是消息中间件(pub/sub)来使用. 与memcache相比,redis支持更多的数据结构,比如string,hash,list,set,bit map,sorted set甚至是geo等等,基本覆盖了日常开发中使用到的数据结构. 而且redis十分高效,当然是建立在合理使用的前提下.

55最佳实践系列:Logging最佳实践

- - 博客园_旁观者
@郑昀汇总 创建日期:2012/10. ASAP (As Soon As Possible)原则. 当你意识到靠现有的日志无法定位问题时,. 当现象难以在你的开发环境重现时,. 请不要执著于枯坐肉眼看代码,因为:一)不一定是你代码逻辑问题,可能是脏数据造成的,是老业务数据造成的,是分布式环境造成的,是其他子系统造成的;二)线上业务处于不稳定中,条件不允许问题定位无限期.