最近在Filepicker.io上花了很多时间研究API,随着JavaScript API 1.0的发布,我们总结了API设计经验,分享给大家,希望我们在使用您的API时,也能像使用自己的API那样兴奋。
规则0:不要随意对API做出改变
API是你与产品使用者沟通合作的桥梁,好比合同,请不要轻易修改和违背。开发者会花时间和精力学习研究你的API,并且把它们融入到自己的产品中。
然而,随着时间的推移,初始版本会逐渐过时并且需要定时推出些新版本。甚至经过一些阶段后,你需要一次性地做出些重大调整。如果可以,在新版和旧版之间提供一个垫片,然后把旧版的API调用映射在上面。这样就不会打破用户在原有旧版本里面的所有接口调用。
在我们早期客户的开发过程中,产品和功能集经常性发生变化,这也就意味着API的累积会越来越多。虽然它能正常工作,但是在处理我们的API时,仍然会有许多不统一的地方。所以,在设计API时,就应该从第一版本开始,采用统一的规范和操作说明,以此来避免后期的不统一。
规则1:给API提供“木头”、“钉子”和完整的架构
提供一些高级功能,里面包含整个工作流程和“原材料”,开发者只需一行代码即可实现整个流程,而那些“原材料(raw primitives)”允许开发者自定义功能模块。
如果有人向你寻求如何构建一所房子,那么你可以提供两个有帮助的东西:第一是直接给他们一所房子,第二是提供工具、指导以及原材料。如果你给他们三块钉在一起的木板,那真是令人沮丧的:首先他们需要找到合适的方法,让木板变成他们所需要的,其次是关于如何应用它们。
规则2:名词、动词和完整的二分图
在传递对象和执行操作时需要注意哪些规则?当你能操纵每个对象时,你就可以为整个API找到很好的候选对象。
这样会让人对所设计的API多一些思考和认识。开发人员使用名词和动词组织成句,使用模型/名词/对象或者其他动词/动作为数轴,画一个网格。如果你能基于某个对象完成特定的操作,那么就把网格中相应的小正方形涂满。对于那些空白的小正方形,应该在文档中表明,给予特殊的警告,并且说明为什么?当把整个网格涂满时,就可以把它当成一个完整的“块”,作为很好的API设计候选对象。
规则3:快速高效地处理API错误
当处理API程序错误时,应该立即抛出异常。应该把用户操作和意外情形下发生的错误归为一类错误返回。提出一致的错误处理方式,下面提供了一些方案,尤其适合设计JavaScript API使用:
- 开发者不应该使用try-catch。如果在抛异常过程中开发人员又制造了错误(或者错误没有很好的记录),那么应该尽快弹出通知。
- 当一些意外事情发生或者用户做了一些“类似错误”(没有做出选择、上传内容无法阅读的情况下关闭对话框等)的时候,应该以统一的方式传回到固定类型的错误中。
当与API进行连接时,可以先看看你的开发库是否可以做些什么,这可能需要对你的代码花些额外的心思,但可以捕获一些常见的错误。例如,限制用户的图片选择,你可以设置{mimetype:“image/*”}或者{mimetypes:“image/*”},filepicker.read()方法调用会接受FPFiles、URLs、DOM文件对象以及DOM输入类型。如果想在IE8中成功读文件,程序库会不顾一切地执行该操作(查阅post),但对于开发者来说,往往功能实现就无需考虑异常和一些错误案例。
规则4:好的API应该易使用
使用API就像是在开发API一样,在开发之前或者初期,你可以让你的客户/朋友也尝试做些同样的事情。
首先需要指明的是,API会把所有的演示方案转换成新的设计。API会用到许多模板文件去做一些简单的事情,对此,我们最好简化这些文件。然后基于用户做一些用户体验,编写指导说明并且检查具体实施情况。站在用户角度去设计,前提是你要喜欢自己的设计和使用体验,然后才能让客户喜欢。