如何设计一个良好的API?

16-10-24 banq
         

这是有关RESTful web API的设计技巧。无论你是在写一个开源库或者内部sdk,甚至只是一个单独的内核模块,下面的这些技巧应该是有帮助的。

要明确

这也许是最重要一点。如果你有一个方法getUser,如果不明确它可能引起一些副作用,最终会导致很多问题。比如getUser明确的只是返回一个用户,不会对用户的id进行增加。

尽可能多的提供更多的行为。不要指望用户会潜水你的源码,以发现隐藏的行为。

让a p i表面积尽可能小

没有人喜欢臃肿的程序,如果你能够暴露更少的api就能完成工作,这对于每个人都是一个很好的体验。

是否人们真的要求你写这个新的api?一直到它是一个真正需要有人去解决的问题的时候,你才可以去做它。

减少样板

尽可能的在内部处理各种细节,以减少客户端的负担。客户端调用的时候做的越少,漏洞才可能越少。

喜欢干净的代码?那就保持你的api很干净,那么,你的api的客户调用就会很简洁。

降低依赖

尽可能的保证你的代码人自我封闭,你有更多的依赖,就意味着潜在的问题会影响到下游代码。

如果你希望从另外一个模块里,获取一块功能,那么尽可能的只提取你需要的。在代码重用和紧耦合和之间有一个平衡,如果功能比较小,那么就值得你自己重新实现它。

返回有意义的错误状态

返回null是毫无意义的,他什么也意味不了。错误信息要能够有可以进行改善的提示。Error.USER_NOT_CREATED 或Error.USER_DELETED都是有意义的。

异常应该有真正的含义

如果你使用的语言没有异常,祝贺你,函数式语言在提供有意义的错误状态方面会做的更好。

一场已经在java领域被滥用,getUser时如果没有发现用户,不要抛UserNotFoundException,而是返回一个正常的错误状态。

比一个蹦溃的程序更坏的事情是,不要因为一个不确定的状态导致崩溃。

对所有的事情要建立文档

文档是无聊的,但必不可少,良好的文档会保存你的理智思考,会避免api消费的很多问题。

一个好的文档包括:

1.有关模块是如何工作的高层次概述

2.公共方法和接口的javadoc

3.如何使用api的案例

不是所有的抽象都需要文档的,一些小类就不需要案例代码。

文档必须是演进,如果有很多问题问同样的事情,你就可能需要把它加到文档里。

太多的文档也是浪费时间,因为你必须保持不断的更新,但是如果仍没有人使用,它就没有什么价值,所以要保证足够的重点和适当的文档。

编写测试

这是是正确性的证明,文档和示例代码都可以包括进去。它为中国提供了巨大的价值,能够让你在事情改变时候,很自信的快速移动。

那些想对你的api实现深入研究的人总是,通过阅读测试实现的,能够更多的了解你的代码行为和意图。这些都是文档无法实现的。

变得可测试

测试你的代码是一回事儿,让人们对你的api更容易地编写测试代码又是另外一回事儿。

你需要有针对调试和产品环境的不同配置。

允许用户选择

不是每一个客户端都以同样的方式调用你的api,有些人可能喜欢同步调用,而另外一些人更喜欢一部回调。

让用户选择他们自己喜欢的方式,你的api就更容易集成到他们现有的编程环境中,更可能地被使用。

不要给用户太多的选择

不要给用户太多的选择,否则他们就有选择障碍,总是提供合理的默认行为,也就是你的api默认的使用方式。

api应该鼓励规范行为,不要让消费者修改内部状态,如果你无意中暴露一些怪异的行为,它会产生一些不可预见的后果。

给出态度的选择就会失去重点,在正确和灵活之间要进行平衡和选择。

总之,设计一个api是一种艺术,需要更多的实践。

How to design APIs that don’t suck

[该贴被banq于2016-10-24 16:29修改过]

         

3