如何创建成功的RESTful API设计

日期:2016-7-28作者:Mark Betz翻译:boix来源:TechTarget中国 英文

RESTful API   API设计   

【TechTarget中国原创】

成功的API设计需要对细节的大量关注。遵循以下三个步骤来做好RESTful API设计。

设计好的API是一项困难的任务,存在很多主观指标。哪怕是完全拥抱RESTfulAPI设计并对其问题域拥有完整视图的小型初创企业最终也会出现命名不一致、界面模糊以及无记录语义等问题。当一家有着许多不同开发团队的大型组织以特定方式遭遇这些相同挑战时,其影响是参差不齐的,往往导致API陷入到一个个烟囱当中,让它们很难显现。在本文当中,我将讨论三种实践,这三种实践可以帮助你的企业API避免这些陷阱。

语义要对

要搞清楚的最重要事情是语义。这个词使用起来非常宽松,但是在这里我指的是API端点以及查询字符串参数的命名,传递的数据结构的布局,HTTP头的使用,以及围绕着返回HTTP状态码的惯例。不同的设计师往往对RESTful(表属性状态转移)接口的基本原则解释有着颇为不同的观点,而解释的质量最终是非常主观的。这一点在端点的命名以及参数和数据结构的使用上实在是太正确了。

API端点名是API对消费者来说最显而易见的东西,比任何其他特性向消费者传达的东西都要多。无论一个端点是否被命名为资源(客户)、进程(存货)或者甚至是媒介(移动),如果那些约定在整个问题域和业务域都一致应用的话API就会更加容易理解。对于大型企业来说,实现这种一致性程度的唯一方式是要有协商清楚的一致约定并且定期应用到各个开发团队上。达到那个理想水平需要在管理上不断实践,而不仅仅是设计好就行了。

除了API端点命名以外,你还有参数命名以及数据结构命名的问题。不同的接口会有不同的数据需求,但是风格约定也应该得到采纳和使用。如果“OneAPIDoesThis(一个API做这个)”,“另一个做那个”,那么API凑在一起就没那么容易理解。这一点同样适用于共同参数或者共同数据结构。如果端点要用一个访问令牌,通常如果他们给它取同样地名字的话会更好。要想就API命名约定得到一些好的提示以及知道如何去应用这些提示,可以看看Netflix或者Twitter这些主要玩家的指南。

发现和存档

即便你有了好的RESTful API设计,且应用了一致的约定,如果他们不能很容易了解到这些设计特性并且探索不同端点的使用方式的话,对于API的消费者来说基本上也没有什么好处的。幸运的是,我们有Swagger,这是我最喜欢的API设计与测试工具之一,也是我一旦经过了最初的概念化阶段开始设计新API时求助的第一个工具。

Swagger在本质上属于用结构化的方式描述RESTful API的一个规范,采用的是要么JSON要么YAML这样的标记语言。围绕着这一规范是一组编辑标记并生成免费东西的工具:存根(stubs)、端点测试,以及好的TML文档。我发现Swagger有两个东西特别。一是由于它是标记性的,你的API规范可以成为特殊“自文档”端点(通常是命名的Swagger)的返回类型。消费者可以用这个端点迅速访问你API的结构化规范。

我喜欢Swagger的第二个点是模型验证。作为给API编写文档过程的有份你要定义端点作为模型类型返回的数据结构。你可以对字段(无论是必选还是可选)进行文档记录,同时还可以对值域和约束进行记录。完成这些以后,你可以用像bravado-core这样的库在运行时验证输入数据是否符合模型规范,并给在验证失败时返回详细的错误信息。这可以节省一大堆的工作,并且给你很大的信心,相信自己的代码是基于合法输入运作的。

访问与可测试性

消费者在跟新API打交道是遭遇的早期壁垒之一是弄清楚它是如何工作的。无论端点的命名有多好,也无论文档写得有多好如何容易获得,作为新客户早期开发过程的一部分大多数开发者都需要测试API。我喜欢的API测试工具无疑是一个叫做Postman 的Chrome浏览器插件。Postman可以让你定义命名的端点集合,以及URL、查询串参数、需要执行的头和体数据。一旦定义好了,一次点击就可以执行端点,并且回报调用的性能以及给出对响应详细信息的访问。

一旦集合定义好,就可以分发给消费者以各种方式自行使用:一是可以上传给Postman服务器,这个过程可以在返回URL客户端后再通过下来访问。这个集合还可以导出为JSON充当你自己服务器上的端点,如果API不开放的话可以优选这种方式。我往往出于这一目的来使用端点和Postman。这是Swagger有所帮助的另一个领域,因为Postman可以导入Swagger规范并且替你生成一个端点集合。再也没有比这更容易的了。

当然,在开发新API时,还有很多其他重要的设计和实现考虑。最重要的影响之一是如何决定对它进行版本控制,这个话题值得另起一篇文章进行讨论了。目前为止,我认为按照上述概括的实践做法已经可以帮助你创建跨整个企业一致性、消费者可发现、按需自文档以及客户端开发者容易测试的API了。总之可以有三种方式帮助避开企业API管理的混乱。

我们一直都在努力坚持原创.......请不要一声不吭,就悄悄拿走。

我原创,你原创,我们的内容世界才会更加精彩!

【所有原创内容版权均属TechTarget,欢迎大家转发分享。但未经授权,严禁任何媒体(平面媒体、网络媒体、自媒体等)以及微信公众号复制、转载、摘编或以其他方式进行使用。】

微信公众号

TechTarget微信公众号二维码

TechTarget

官方微博

TechTarget中国官方微博二维码

TechTarget中国

评论
查看更多评论

敬请读者发表评论,本站保留删除与本文无关和不雅评论的权力。

API>更多

  • API项目中 官方客户端不再是可有可无的

    在API项目中,有官方支持的客户端才能给API社区传达积极的信息。没有官方支持客户的API就像是没有方向盘的汽车。可能是辆好车,但是却哪儿也去不了。

  • Google收购Apigee,焦点在于企业本身还是API?

    Axway的Suraj Kumar认为Apigee收购案不一定是件好事。尽管Google也许会像Borg一样行动,这也许预示着Google的态度需要转变。

  • Google的新收购是否意味着API变得更酷了?

    Google对API管理解决方案提供商Apigee的收购,我们应该怎么评价呢?是为了打造一个改变游戏的联盟吗?或者只是技术巨头想尽快吞食市场份额的尝试?

  • 如何创建成功的RESTful API设计

    设计好的API是一项困难的任务,存在很多主观指标。哪怕是完全拥抱RESTfulAPI设计并对其问题域拥有完整视图的小型初创企业最终也会出现命名不一致、界面模糊以及无记录语义等问题。

相关推荐

技术手册>更多

  • 2011年SOA精彩内容汇总

    时光飞逝,转瞬已经步入2012年,在十二月份,SesrchSOA.com.cn对于相关的一些领域做出了总结和展望,希望对于读者具有一定的指导意义。同时,编者也在这段时间内,对于过去一年中网站上的原创内容进行了一次全面的回顾,为大家总结了一些较为实用的技巧和分析,内容涉及SOA现状以及发展、SOA实操技巧、热门话题云计算以及Web服务。下面我们就来看看这些内容。

  • SAML技术手册

    安全是所有Web项目在设计时都要考虑的一个重要因素。无论是选择最短口令,决定何时使用SSL加密HTTP会话,还是通过自动登录cookie来识别用户,都经常要付出重大的设计努力,以保护用户的身份信息和他们可能存放于Web站点的其他资料。糟糕的安全性可能带来公关灾难。下面我们就来具体看一下SAML在这里所起到的重要作用。

  • REST开发者RESTful资源指南

    维基百科把表述性状态转移(Representational State Transfer ,REST)定义为“分布式超媒体系统、如万维网的一种软件架构形式”。Web服务的RESTful方案被广泛视为SOAP的一个更简单的替代方案。许多大型的Web服务提供商如亚马逊、Twitter和谷歌都在广泛地使用它。在这本技术手册中,我们将为您提供一些RESTful资源和技巧。

  • 开源PaaS技术手册

    开源业界向来不太平,关于诸多技术的开源未来足以让很多粉丝兴奋躁动起来。商业软件开始揉进开源技术,开源技术也成为IT大佬们得基础架构,这一种趋势蔓延的缓慢有有力。在广告漫天飞得云计算中,开源的分量有多重?是否走向云端就意味着走向开源?开源的PaaS如何选择?如何为开源项目选择PaaS厂商?哪些服务平台值得我们关注,下面我们一一来揭晓。

TechTarget

最新资源
  • 安全
  • 存储
  • CIO
  • 数据库
  • 服务器
  • 云计算