API索引

最近在调用多家公司的API接口,也参考了TB的API的设计。列举关键点备忘:

API文档

先从调用者的角度来考虑这个问题吧。文档应该是所有API使用者就关心的问题。问题也来自于这个文档本身。当然很多问题是想想就明白的愿意所在的。文档版本的维护,可以说各家特色不同。糟糕的情况可以用“混乱”来形容。有时候销售人员发给我们的最新版本,并不是公司对外的最新版本,总是为了省事通过Email附近来发送,结果这个附近就是使用了N年的旧版本。有时候甚至是个补充协议版本。啥意思,告诉你文档本身总体是对的,大概补充一个文档说这里需要修改,那里需要补充,你就明白什么叫抓狂。

api.***.com这样的在线文档不进行维护更新。这恐怕也是很多公司的情况,文档的更新总是一个难题。但是这样的API文档,你不维护也是要维护的,否则所有最新的接口难道要通过和开发人员沟通才能获取得到。先不说有没有这个接口,就是把所有接口翻阅一遍,大家的成本也都不低了。

API返回示例数据
这个也很重要,很多公司API文档都没有返回结构的示例。说实话一个个接口测试调试,是会让开发者抓狂的事。如果您的文档是足够可以信任的,那么文档中的示例也请保持更新和维护,这样使用的同学会很Happy

测试环境
或者说可以称为沙箱的东西。记得和E公司做交流沟通的时候,大家都认可,看API文档那是纸上谈兵。还是需要提供测试环境的API做调试使用的。但只是提供一个测试环境的APPKEY,觉的已经不能满足要求的。这种还需自己写代码才能看到数据返回形态的原始方式非常落后。所以一个可以在线测试的API工具一定是必不可少的。如果按这个逻辑,这个测试工具,就不紧紧支持测试数据,还是可以支持在线数据的,这样可以很方便的帮助开发人员调试。

SDK提供
发现很多公司都不提供SDK的。即使提供,那SDK也是很粗糙的,或者是缺少语言版本。如果真心要做好API,还是建议封装一套好的SDK供给自己使用,也提供给大家使用。

错误代码
先撇开所有的高端理论,错误代码不一定非要是什么“400”,“500”的,同样可以使用英文,只要统一就好。最早期的设计受REST的影响,很多步伐就迈不开了。不管什么愿意,返回的错误代码优先是清晰明了。如果少了参数就要提示少了参数,数据类型不对,就类型不对。切莫搞的很高深,哭和苦的都是API开发解释人员。就因为你提示不清楚,开发的人无头绪调试,您还要重复解释。

API用户授权
这里主要是通过API访问一些用户个人数据,如果平台给第三方应用提供用户数据,就需要使用这个。
OAuth2是个通用规则,不多谈,主要涉及授权的一个过程,包括access_token的访问时间问题。​

API授权使用
可以理解为系统输入设置​。具体看这张表,参数这么设计就对了。TB还有一个自己的特点:定义了基本的数据结构,需要什么字段就返回什么字段,方便系统优化。

这里有一个问题要问你自己?为什么要对data进行sign呢!走Https就可以不需要这一步。

API平台工具
测试工具、API文档、API参数公司、API Access_Token工具、API错误代码工具

SOAP
*程公司使用的是这种协议。原因很简单,使用的.NET。确实如果直接使用.NET的VStudio来调用是非常方便的。但现在不是.Net系统使用起来还真是不方便。使用的还是HTTP方式,所有通过Post方式将数据发送过去,不过拼装SOAP格式真是要命。也总算是学好原生使用SOAP协议。

GZIP压缩
能想到的最简单的节省流量的办法

API的其他

  • 主动通知:通过HTTP长链接实现
  • API异步:生成任务ID号,轮询ID号状态,下载任务数据
  • API定时任务:定时发送请求,设置回调地址通知
  • API的Javascript调用:以前没相关JS如何调用API,通过cookie的方式是个不错的选择。这就要求任何调用前都必须将sign和timestamp填入到当前页面的cookie中(必须服务端填入)

PHP环境(5.1以上版本)的签名实现方式:

$app_key = '';/*填写appkey */
$secret='';/*填入Appsecret'*/
$timestamp=time()."000";
$message = $secret.'app_key'.$app_key.'timestamp'.$timestamp.$secret;
$mysign=strtoupper(hash_hmac("md5",$message,$secret));
setcookie("timestamp",$timestamp);
setcookie("sign",$mysign);
​

API服务器端实现

{未完待续}

总结:

  • API文档尽量维护Online的版本,保证唯一参考源
  • 在线测试工具,必须提供,越完善越好
  • API用户授权使用Oauth2
  • API授权使用签名、时间戳