资讯中心

不得不引起重视的API设计问题

如果你是一个程序员,你会知道在交互组件化软件的世界里,没有比API接口更重要的东西了。API之所以重要,是因为它的作用往往是两个极端化的呈现,开发方式恰当与否,最后的结果要么是帮助功能整合,要么是直接危及整个项目。

 

API开发中,开发者和架构师犯的其中一个最重大的错误是忽视自己的用户API设计能否很好地适应开发者、语言和其他API组成的生态体系是一个至关重要的问题。接下来赛合一数据”就来浅谈关于API开发设计的一些问题事项。

 7.jpg

常见的API设计问题

 

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

 

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

 

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

 8.jpg

API设计的一般规则

 

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

 

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

 

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

 

9.jpg


常见问题

 

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

 

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

 

结语:API开发问题可能会毁了一个应用,这种破坏往往比其他类型的架构错误都要快、都要彻底。所以赛合一数据”善意提醒各位,多花点时间在API设计上,这样你才可能有效预计到当前的错误状态未来的变化,当你能发现和把控这些问题的时候,你会感激当初花那么多的时间投入是值得的。