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的收购,我们应该怎么评价呢?是为了打造一个改变游戏的联盟吗?或者只是技术巨头想尽快吞食市场份额的尝试?

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

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

技术手册>更多

  • BPM项目错误规避指南

    业务与技术的交叉点正是BPM关注的焦点,这也是大多数重大IT问题出现的地方,通过为业务分析员和软件开发人员提供通用的工具,BPM有希望使应用集成发生革命性变化。正因为这样,技术不能够单独支撑BPM的全部内容,也不能单独解决业务流程的所有问题。业务是BPM依托的另一方面。但是企业在进行BPM项目时却会遭遇种种问题,而有些问题是可以通过前期工作避免的,本期TT SOA技术手册介绍如何合理规避BPM项目中的错误,同时提供BPM技巧和工具信息。

  • Web服务描述语言:WSDL

    Web服务描述语言WSDL是用XML文档来描述Web服务的标准,是Web服务的接口定义语言,是Web Services Description Language的缩写它用一种和具体语言无关的抽象方式定义了给定Web服务收发的有关操作和消息。就其定义来说,你还不能把WSDL当作一种对象接口定义语言,WSDL保持协议中立,但它确实内建了绑定SOAP的支持,从而同SOAP建立了不可分割的联系。

  • “软件+服务”SaaS和SOA

    SaaS和SOA 号称“大小S”,软件架构是面向服务的SOA,软件应用出现SaaS新模式,中国软件与服务市场可谓是世界IT市场潜藏着的最大“蓝海”。应用软件开发厂商向SOA领域涉及的程度越来越深,SOA已经无处不在。随着SaaS的愈发火热,SOA的继续深入,业界出现了“软件+服务”(S+S)战略,旨在打通“内部业务整合(SOA)+外部业务拓展(SaaS)+丰富用户体验”等多重资源,实现SaaS和SOA“鱼和熊掌兼得”。

  • 大数据应用分析

    大数据已经不再是媒体炒作的流行词语,它正在不断冲击着政治、商业、社会、科技诸多领域,已经成为新一轮技术变革的最强音。

TechTarget

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