API设计:如何正确开发应用程序接口

日期:2014-2-10作者:Tom Nolle翻译:boxi来源:TechTarget中国 英文

API   应用程序编程接口   REST   SOAP   

【TechTarget中国原创】

在交互组件化软件的世界里,没有比让组件之间以及组件与移动设备和浏览器之间进行连接的应用程序接口(API)更重要的东西了。用恰当的方式开发出来的API,可帮助功能整合与开发者的忠诚;而用不当的方式开发则会危及整个项目。 

有三种方式可助API开发走到正确的一边:

  • 了解应用和使用约束;
  • 处理组件结构并绑定框架; 
  • 确保优雅地处理变更。

API把功能和服务暴露给开发者。API的使用方式及服务系列展示是初步设计的驱动力。在API开发中,开发者和架构师犯的其中一个最重大的错误是忽视自己的用户。API设计能否很好地适应开发者、语言和其他API组成的生态体系是一个至关重要的问题。

常见的API设计问题

REST与SOAP之争就是API约束集的一个例子。只要应用已经存在相互依赖的地方,新的API显然应该与之协调一致。不那么明显的是大多数API是组件化和功能显露趋势的一部分。这种运动随着时间迁移会让一组API越来越朝向REST或SOAP的方向,因此要确保对这种迁移的预期。

架构师很容易会被遵循对象架构和框架绑定伤到。挑选合适的API设计很重要,因为让开发者采用一个与其所开发应用的架构不匹配的接口是很困难的。应该注意的是RESTful API往往展现的是资源,而SOAP API展现的往往是远程流程或过程。

一些协议过去往往将API与API用户绑定在一起,且经常跟Web应用一起,这种协议往往是HTTP/HTTPS。HTTP的使用一般会配合超文本标记语言(Hypertext Markup Language)或XML语言的数据格式,或者在客户端设备上用JSON或JavaScript,使得很容易就能通过API创建图形用户界面,但在浏览器访问并非应用的意图所在时就不合适。有的应用和API可能会使用特殊的TCP协议或UDP协议端口而非标准的Web端口80。尽管这能帮助将API流量与Web活动区分开来,但也有可能存在防火墙/安全方面的影响,需要进行特殊的系统配置才能要么将API暴露出来,要么在远程使用它们。

API设计的一般规则

大多数的API可被视为由动词与名词组成的语法。比方说,带动词的句子表示一项请求动作(get、put、delete),而名词则表示与该动作相关的参数。总是生成一个状态或结果变量是一个很好地做法,因为这能够传达出错误状态或成功执行的信息。出错状态应该全面综合,足以明白无误地传达出问题所在。

API的语义,即所提供功能的语法也很重要,因为API清晰表达其服务和参数的能力可减少开发者的错误。一个关键点是如果API代表的是一个有状态的服务,那么功能语义就应该是面向会话式的(寻找记录、更新记录、删除记录),这样的有状态属性服务就可以很清楚了。

由此得出结论,如果在本例中更新和删除功能是对上一次定位的数据元素进行操作的话,那么更新和删除功能不用提供自己的数据元素键,这是多余的,但也会产生令开发者困惑的风险。另一方面,无状态服务永远都必须提供所有的数据,因为没有可供推断的会话上下文信息。

常见问题

更新或变更API导致的语法问题往往被忽视。API有两端,变更过程会令其失去同步。有些架构师会在API里面放一个版本变量来确保两端预期的是相同的格式。API的服务器端和客户端至少都应该进行基本的验证来防止变更导致语法不匹配,从而避免信息被弄乱或导致应用崩溃。

另一个常见问题与数据格式有关。XML是传递参数和交换信息最常用的方法,适用于REST和SOAP接口。但XML的处理却是重负载的,对表达结构化数据最有价值。而REST中,JSON则因为更容易使用的同时还提供了一些在API开发中广为采用和预期的特殊变量类型而受到喜爱。在API交换严格定义的数据元素时,JSON似乎是RESTful交换更好的选择。

API测试往往集中在应用生命周期管理的过程中。有些测试正好是这个阶段的,但是也应该有特殊单元测试流程,这些流程旨在验证API,并确定API可优雅地执行,哪怕是数据存在错误的时候。API的数据绑定和类型定义越宽松,传递信息会导致随后错误或崩溃的风险就越高。这正是为什么对变量要进行严格约束,并对每一个API都要用一组数据进行测试之所以重要的原因。

API开发问题会毁了一个应用,这种破坏比几乎任何其他类型的架构错误都要快、都要彻底。多花点时间在API设计上,以便能预计到当前的错误状态,以及未来的变化,这些时间的投入是值得的。

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

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

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

微信公众号

TechTarget微信公众号二维码

TechTarget

官方微博

TechTarget中国官方微博二维码

TechTarget中国

评论
查看更多评论

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

作者>更多

Tom Nolle
Tom Nolle

关于作者:Tom Nolle是CIMI公司的总裁,这家公司成立于1982年,是致力于电信和数据通信的战略顾问公司。Tom Nolle是IEEE、ACM、Telemanagement Forum和IPsphere Forum的一员,著作有关于Netwatcher方面的书籍。

API>更多

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

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

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

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

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

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

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

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

相关推荐

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

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

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

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

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

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

  • API版本化与迁移五大策略

    API版本化和迁移是不得不解决的问题,特别是在应用程序接口和不断变化的业务优先级绑定越来越紧密的当下。但是,如果采取一些关键步骤,改动API就不会造成悲剧。

技术手册>更多

  • SOA数据集成学习指南

    Web服务发展初期,人们的目光都集中在应用集成和工作流程上。标准如SOAP、WSDL、UDDI和BPEL创建和企业服务总线(ESB)成为一个能够进行这种类型集成的新的技术。

  • 可扩展标记语言:XML

    XML即可扩展标记语言,是Extensible Markup Language的缩写。它与HTML一样,都是处于SGML,标准通用语言。Xml是Internet环境中跨平台的,依赖于内容的技术,是当前处理结构化文档信息的有力工具。扩展标记语言XML是一种简单的数据存储语言,使用一系列简单的标记描述数据,而这些标记可以用方便的方式建立,虽然XML占用的空间比二进制数据要占用更多的空间,但XML极其简单易于掌握和使用。 

    XML实际上是Web上表示结构化信息的一种标准文本格式,它没有复杂的语法和包罗万象的数据定义。XML同HTML一样,都来自SGML(标准通用标记语言)。SGML是一种在Web发明之前就早已存在的用标记来描述文档资料的通用语言。

  • 云应用性能管理和测试教程

    云里来雾里去的云计算讲了好多年,其实对于大众来讲对这个概念仍然是有些摸不着头绪。那么对于已经应用了云服务的企业而言,在实践中有哪些技巧可以参考或者有哪些经验可以分享呢?在这期技术手册中,我们将一起来关注云应用的可用性,如何进行云应用的监控,云服务中间件如何?同时我们将侧重于云应用性能管理以及云应用测试的内容。

  • 企业架构师工具包

    企业架构师如何创建一个有用的工具集呢?目前实践者正在将UML和TOGAF以及其他工具连同使用,从而能够构建出软件模型解决业务构想变成工作系统最重要的一步。但是需要高度熟练的架构师,来创造业务架构参考模型。成功的软件架构师会发现和企业匹配的工作参考模型会成为他们自定制添加“工具”的框架。下面专家的一些建议可以为我们提供一些引导。

TechTarget

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