如何创建成功的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>更多

相关推荐

技术手册>更多

  • SOA与敏捷开发实战演练

    SOA是一种架构,敏捷是一种方法论,架构和方法论是可以一同使用的,它们本质上是互补的。而且,SOA和敏捷的目标相同,它们都承认(1)变化是必然的(2)组织需要有效地应对变化。所以,我们期望在构建SOA时,能够选择敏捷方法论,反之亦然。本技术手册给出了二者结合的完美之道。

  • SOA中间件最大化大数据价值指南

    对于技术专业人员,管理大数据已经越来越重要。研究表明,越来越多的组织开始处理大数据,但即使是有多年的经验的工作人员,也会造成很多麻烦。

  • 移动ALM学习指导

    移动应用生命周期管理(ALM)是一个流程,是一套实践,是针对智能手机和平板电脑进行的计划、编码、测试和部署应用。现在移动不仅仅只是简单的生产力工具,它正在向业务策略看齐。因此,组织也迅速地向员工们提供了高端的移动应用,从而交付不同来源的数据和服务。这就给软件团队提出了双重难题。同时他们又承受着快速交付的压力。他还要努力解决在生命周期各个阶段提出的一些移动ALM挑战。本手册概述了移动ALM的挑战,并且探索了不同的方法,使软件开发人员得以处理那些挑战。

  • SOA开发精彩技巧汇总

    我们精选了2009年最受读者欢迎的技巧类文章,涉及到SOA的多个方面的内容,从最热门的云计算到协作型计算MapReduce;从各类SOA模式到REST战略的创建;从SOA颗粒度的获取到ESB选型技巧等等,尽可能涵盖您所关心的问题。下面让我们看看详细内容。

TechTarget

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