必威体育下载克里斯蒂安·海尔曼

您当前正在浏览数据可移植性类别的存档。必威体育简介

“数据可移植性”类别的存档

我希望有一个很棒的Ajax API

星期二,4月8日,2008

从…回来在苏格兰高地舞有趣的是,人们似乎还没有完全相信api的必要性以及它们在未来几年的web开发中所扮演的重要角色。我想这在一定程度上是基于使用api的经验,这些api并没有很好地向非极客解释,而且不一致或难以使用。只有在试图找到没有多少有趣的信息一点点如果所有你想做的是编写一些代码(除非你有老学校黑客/饼干的头脑和不考虑花上几个小时看着hexdumps试图找到一个方法来得到无尽的住在一个游戏浪费时间)。

在我接受采访时Paul Boag在我指出,设计一个好的API与设计任何其他用户界面(包括web页面)一样重要。加雷思Rushgrove在他精彩的谈话中同意了如何成为一流的网络公民。我还指出,在这个问题上缺乏清晰和容易的教程和文章,所以我决定现在就试一试。

设计一个很棒的AjaxAPI

作为一个例子,我将使用最近发布的谷歌翻译API,指出它的优点,列出我认为缺少的东西。我就不写了API但要解释为什么我认为缺失的部分很重要。这不是对谷歌的攻击,我真的很喜欢做这个API想让它更容易使用,所以不要难过,我真的脱掉了你给我的帽子API就像那样!

当我们在JavaScript中讨论Ajax api时,我认为以下几点非常重要(Ajax暗示了这一点,但是您会惊讶地发现aREST API作为Ajax发布):

  • 好的文档
  • 使用例子复制+粘贴
  • 模块化
  • 将结果链接到条目
  • 提供灵活的输入
  • 允许自定义对象传输
  • 涵盖可用性基础知识

文档和演示

让我们从一个积极的方面开始Google Ajax语言API是伟大的。您在一个页面上拥有所需的所有信息,包括复制和粘贴示例。这允许你通过API在网上,离线阅读,甚至可以打印出来,在拥挤的公交车上阅读,而不必拿出笔记本电脑。

提示如果你提供的是复制和粘贴的例子——这是你应该做的,因为这是人们做的第一步——确保他们工作!我在必威体育下载书中得到了惨痛的教训JavaScript开始与DOMAjax脚本和没有什么比展示代码片段而不是完整的例子更危险的了——人们会复制和粘贴脚本的部分,试着运行它,然后发邮件告诉你你的代码被破坏了,或者更糟的是,在亚马逊的书评中抱怨。如果你提供复制和粘贴的例子,确保他们都独立工作。

谷歌提供解释API是,你能用它做什么,所有参数及其含义的列表。这对于初次浏览的用户来说非常好。对于铁杆读者,它们还提供了类参考。

使用的例子

第一个代码示例非常好,你可以复制和粘贴它,如果你的电脑连接到互联网,它会工作,或者它会工作,如果HTML有一些修正。

首先它缺少a文档类型,这有点烦人,因为它是HTML文档。更重要的一点是没有设置编码。的生活例子版本两者都有-有点讨厌,特别是当我们谈论不同的语言时,以传统汉语为例,正确的编码是必须的。

(注意:具有讽刺意味的,看来WordPress做得不好是因为某些原因…)







??????????



提示:确保您向人们解释您的代码示例需要internet连接和其他依赖项(如require)HTTP因此必须在本地服务器上运行)。Javascript历史上除了浏览器没有其他依赖项,这种情况最近发生了变化,可能令人困惑,尤其是当您在后台使用Ajax时,比如某些flash/Ajax API!

模块化是好!

在某种程度上让我感到不安的第一点是google.load(“语言”,“1”)行,但是有一个直接的解释。

第一个脚本包含加载一个泛型Google AjaxAPI有一个load ()方法添加其他,较小的API构建在这个之上。在这种情况下,这行代码意味着您希望加载该语言API版本号为1的。

这看起来很笨拙,你会得到不好的反馈(似乎没有什么比一个包含解决方案的脚本更好的了),但实际上是相当聪明的。

通过模块化基础库中的Ajax代码更改核心功能将被要求实现者容易,包括他所需要的api版本号你可以让它实现者升级的选择,而不是打破旧的实现或携带的重量完全向后兼容。

是的,最理想的情况是,您永远不必更改您的功能API-添加新功能-但在现实世界中,不断的变化将使你有必要打乱原有的API。不存在为永恒而构建的完美代码。在基中使用加载器函数API也很聪明,因为这意味着实现者不需要更改URL。

进去的东西应该出来。

这就是谷歌造成问题的地方。这两个google.language.detect ()google.language.translate()方法非常酷,因为它们提供了发送字符串和定义回调方法的功能API返回一个值。然而,在这两种情况下,返回的对象都给出一个结果和状态代码,但不是输入的。你会得到各种各样的其他信息类文档),但拥有原始条目将非常有用。

为什么?Ajax的优点在于它是异步的,这也是它的弱点。这意味着我可以在后台并行发送大量请求,并等待结果。然而,这并不意味着请求也以正确的顺序返回!

这意味着如果你想循环一系列的文本来翻译,以下是一种不安全的做法:

var翻译=['一',' 2 ',' 3 ',' 4 ',' 5 ',' 6 ',' 7 ',' 8 ',‘九’,‘十’);
var gtl = google.language.translate;
(var = 0, j = translations.length; i gtl(翻译[我],“en”,“德”,函数(结果){
如果(!结果.错误){
var container = document.getElementById(' translation');
container.innerHTML += result.translation;
}

});
}

相反,您需要将数组计数器的增量包装在递归函数中:

var翻译=['一',' 2 ',' 3 ',' 4 ',' 5 ',' 6 ',' 7 ',' 8 ',‘九’,‘十’);
var gtl = google.language.translate;
var = 0;
函数doTranslation(){
var gtl = google.language.translate;
如果(翻译[I])。{
gtl(翻译(我),“嗯”,“德”,函数(结果){
如果(!结果.错误){
var container = document.getElementById(' translation');
container.innerHTML += result.translation;
我+ +;
doTranslation();
}

});
}

}
doTranslation();

这是安全的,但是我们失去了让多个连接并行运行从而更快地获得结果的机会。如果结果是API电话里有原文,事情会更简单,例如,我们可以填充一个result对象,然后用这种方式将正确的请求与正确的结果匹配:

var翻译=['一',' 2 ',' 3 ',' 4 ',' 5 ',' 6 ',' 7 ',' 8 ',‘九’,‘十’);
var gtl = google.language.translate;
var结果= {};
(var = 0, j = translations.length; i gtl(翻译[我],“en”,“德”,函数(结果){
如果(!结果.错误){
results[result.input]=result.translation;
}

});
}

更简单的是传递一个事务ID,它可以是循环的计数器。当然,另一个选择是允许输入的数据具有更大的灵活性。

提供灵活的输入

输入文本与结果的匹配和事务ID的匹配仍然意味着对API,这并不是很好,因为它既要花钱,又会对服务器和客户端造成同样的打击。一个更简单的选项是,不仅允许字符串作为文本参数,还允许字符串数组作为文本参数。然后返回的结果也会变成一个数组,调用翻译引擎的大量开销会在服务器上通过一次调用来完成,而不是大量调用API调用。

这不难做到,大多数JavaScript框架方法都是这样工作的,通过检查第一个参数的类型并相应地进行分支。您甚至可以更进一步,允许实现人员将自己定制的对象作为第三个参数发送。

传输一个自定义对象允许实现者编写更少的代码

的好处是,您可以添加更多的参数API只对实现进行特定的调用。很可能这是对命名空间的引用,以避免重复长方法名或全局变量。您可以从提供任何Ajax调用在可用性方面都有意义的参数开始。

考虑Ajax可用性

任何Ajax调用都应该为用户提供的主要功能是超时。没有什么比得到一个拥有更多交互界面的全新Ajax世界的承诺,却被困在旋转的轮子上,或者更糟糕的是点击链接却一无所获更令人失望的了。现在的语言API没有这样的东西,你必须用手滚动一个解。您还必须检查错误状态代码,以查看是否无法检索数据,并以这种方式调用连接的失败案例。

一个很好的API会给我这些选择,很可能都滚入了一个参数对象。

我的梦想翻译API

考虑到所有这些,最好是API提供这些选择:

google.language.translate(输入、参数);

参数是:


输入//字符串或数组
具有以下属性的参数//对象
sourceLanguage:字符串,
开发:字符串,
transactionId:字符串,
customparameters:对象,/ /运输
超时:整数,/ /(以毫秒为单位)
失败:函数(因此,params),//(超时或错误时调用的方法)
成功:函数(因此,params),//(当一切正常时调用的方法)

的返回数据API应该提供结果和参数。这将使实现者的生活非常容易。

总结

总之,下面是我对一个伟大的Ajax的期望API:

  • 有一个很好的文档,有完整的类文档支持的即时复制和粘贴的例子吗
  • 构建您的API模块化,并允许实现者选择他们想要的版本
  • 提供一个钩子来链接。的结果API方法输入初始数据。最简单的方法是重复这些数据,更复杂的是允许连接ID。
  • 允许发送多个值,它会节省你API调用和实现者破解了返回顺序不可靠的问题。
  • 允许实现者添加一个自己的对象来发送和返回,以允许名称空间和其他数据状态保留。
  • 允许超时,不信任连接。

这是一项正在进行的工作

我希望你们在这里找到了一些可以认同的东西如果你们知道要补充的东西,留下评论。