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授权使用签名、时间戳

Kindle字典功能

继续写关于Kindle的故事。这次说说字典功能,这也是喜欢电子书的重要原因。传统的纸张书籍,遇到生僻的字,或是一些科普内容,查阅总是很不方便的。而Kindle只要划屏取词就可以了。这里要说一下Amazon的APP对取词的优化,这一点到希望能移植到KP上。APP上的取词最早是要一个个字母滑动匹配的,后来轻点击就自动取词而不是字母。这样特别是看英文文档的时候翻译就方便了很多。

Kindle Paperwhite字典翻阅
KP默认会赠送词典的。KP上会根据系统语言加载特定的字典文件(而且无法从Librery中删除,有些字典只显示在Librery中)。因为中文系统,所有会有两本字典,一本是《现代汉英字典》,一本是《现代英汉字典》,所有对于我这种只能看中文或英文书籍的用户是够了。而且在KP上会有一个专门的字典目录,在存放这些字典。你是可以在KP上打开字典,就像真实生活中一样,也是可以翻阅这些字典的,它其实本身也是一本书。

Kindle Paperwhite添加字典
但如果看古文或是遇到中文生辟字(笺jian谱),你知道是什么意思吗?这个时候怎么办,现在只有汉语或英汉2本字典,我们还需要一个《新华字典》。KP上安装字典还是很方便的。安装字典不复杂,首先找到想要的字典文件(网上搜索Kindle字典下载或是Link)。那后将字典.mobi文件Copy到documents\dictionaries里就可以了。接下来就是设置字典了。如果一种语言下有多本字典,KP会让你选择其中一本使用。也就是说如果要实现“汉英”或“汉汉”你需要在这里选择,否则KP不知道你是要翻译成英文,还是汉语解释。这就要看你取舍了。

Home -> Menu -> Settings -> 设备选项-> 语言和字典 ->字典

Kindel APP字典使用
Kindle APP上是就没有字典的目录了,而且赠送的字典在这里也不会显示。但APP上使用字典却有不一样的方便。点击图标上的“惊叹号”,就可以选择使用什么语言进行翻译了。但是很悲剧,对于“日文、法文”等,一旦你下载字典会提升你“该字典不能在您所在的国家/地区使用”。好在最下面有“百度/百度百科”的外联方便查询,也算是字典功能吧。

字典关联问题
因为KP字典和语言对应。英文字典只对英文书籍中有效,如果你发现下载的字典在英文书籍中无法取词,用Calibre编辑一下字典的源数据,将语言栏改成英语。反之依然,如果要翻译中文书籍中的单词,将语言栏改成中文。

这里其实还有些比较深奥的东西。每个mobi词典文件都有这三个关于语言信息的标识项,很可惜calibre目前无法对三个语言项进行正确修改,但可以通过16进制的方式进行修改。具体可以查看参考中的链接,如果遇到字典无法查找的情况,多半是这里出问题了。

词典文件区域代码 Locale
读入语言 Input Language
解释语言 Output Language

Continue reading