如何设计一个良好的API?

这是有关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修改过]