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方面的书籍。

技术手册>更多

  • 智能BPM与业务流程工具

    Gartner认为iBPM要比运营型智能平台更优秀,表现在以下几个方面:iBPM套件提供更好的工作流,适配性案例管理以及结构化流程协调能力。

  • 云BPM新常态解析

    云端业务流程管理已经不再是什么新鲜事,更不再是什么可怕的方法来管理重要的业务流程。现在,它已经普遍被认为是一种新常态。组织已经从这一技术中获益,使它来更有效地访问和管理企业信息。

  • 企业IT集成指南

    随着云技术的不断采用,现代企业都面临着重大的集成问题。现在已经不再是把企业内部的数据和应用简单地缝合在一起,企业IT现在面临着整合着外部与内部信息的难题。

  • API开发与管理大作战

    2014将会是API管理方法新旧PK的一年,据Delyn Simons说,她领导了Mashery开发者的外展团队。应用编程接口(API)的主流化和私有化在新的一年也将掀起波澜,她在波士顿“Future Insights Ultimate Developer Event 2013”大会上预测说。