设计API的十条准则

杨竹青

API是接口 - API本身并不实现任何功能，它只是一个接口定义（想想ActionScript中的Interface）。这是API最重要、最明显的特点，也是API的目的所在。无论何种情况，请将这一点牢记于心
API不是代码库 - 一个好的API一定有明确的功能目的。它绝不是一堆函数（function）原型（prototype）的集合
公开的API能不改变则不改变 - 当这些API对外发布之后，要想改变是非常痛苦的（你必须通知所有的使用者），因此在设计之前，一定要三思，例如方法名、参数类型，返回类型，等等。
API是神秘的 - API应该把所有对外不必知道的信息全部封装起来。例如使用者向我提问："你是一个天才么？"，我应该回答"我是一个天才"，但不要回答"我为什么是一个天才"。
关注你的API的使用者 - API真正投入应用才是健康的。要关注那些应用你的API开发各种有趣应用的代码。
不要迷信文档 - 好的API是一眼就能看明白的，不要指望那些渴望利用你的API做些小应用的开发者会耐心地花几个小时在你的文档上
文档、存档很重要 - 虽然刚才提到不能依赖与文档，但是作为API本身的开发者，一定要重视，因为你自己必须搞清楚内部的机理，这样便于日后的维护和扩展
要讲诚信 - 不要为了取悦一部分人而让另一部分人不知情，这是非常可怕的。我们越来越生活在一个开发、自由、透明的时代。有任何问题，就坦诚说出来。
没必要来什么"惊喜" - 优秀的API一定是"可预见的"，也就是说，开发者在阅读你的API说明时，就已经知道哪些应用可以做，哪些应用不可以做了，不要让开发者开发到一半突然发现有一个新的应用。那不是对开发者的肯定，反而是对这套API的讽刺。
要快乐 - API的工作是需要付出责任心并且逻辑严谨的。但是千万不要丧失一个最重要的原则："快乐"！要快乐，要认识到你这套API能给你带来的快乐和成就感！