什么是API

我们从API的功能、分类、设计、实现、用户来看什么是API。

API是应用程序组件之间通信的接口

--wiki:Application Programming Interface

In computer programming, an application programming interface (API) is a set of subroutine definitions, protocols, and tools for building application software. In general terms,** it's a set of clearly defined methods** of communication between various software components. A good API makes it easier to develop a computer program by providing all the building blocks, which are then put together by the programmer. An API may be for a web-based system, operating system, database system, computer hardware, or software library. An API specification can take many forms, but often includes specifications for routines, data structures, object classes, variables, or remote calls. POSIX, Microsoft Windows API, the C++ Standard Template Library, and Java APIs are examples of different forms of APIs. Documentation for the API is usually provided to facilitate usage. The status of APIs in intellectual property law is controversial.

可见，API一般是指一个系统对外的接口，例如：

• Libraries and frameworks
• Operating Systems
• Remote APIs
• Web APIs

抽象概念在编程中具有核心的地位，而实现上的细节被屏蔽在API的实现层，一个模块对外的抽象概念的入口就是API。

--Implementing abstraction

In general, abstraction is implemented by what is generically termed an Application Programming Interface (API). API is a somewhat nebulous term that means different things in the context of various programming endavours. Fundamentally, a programmer designs a set of functions and documents their interface and functionality with the principle that the actual implementation providing the API is opaque.

API分有状态和无状态两类

API应该有分面向对象的有状态API和函数式的无状态API。

有状态API

• 在C语言里，写一个结构体，针对该结构体所代表的资源，提供一组对称操作函数
• 在C++语言里，写一个类，针对这个类内部所持有的核心资源，提供一组对称操作函数
• 在Java或者C#语言里，写一个接口，针对这个接口背后可能持有的资源，提供一组对称操作函数
• 在Lua里，写一个table，针对这个table所持有的资源，提供一组对称操作函数
• 在JavaSctipt里，尽量使用面向对象的方式提供API

之所以说是有状态，是指，这组操作之间依赖了彼此操作的状态，例如：

• Open、Read、Write、Close
• Init、Load、Pub、UnInit
• Create Add、AddRange、Remove、RemoveRange、Clear
• Insert、Update、Delete
• Start、Update、Finish

公共的参数一般会在Open、Init、Create、Start的时候一次性传入、后续的Read、Write；Load、Pub；Add、Remove；多次Update等都是针对共同的资源操作，并且对资源的操作有副作用，使的资源的状态发生变化。

无状态API

• 在Http里，设计Get、Post、Put、Delete的API，也就是RESTFul API，由于HTTP连接无状态的特性，使得每次调用都是独立的，无状态的，所以设计API的时候也要考虑幂等性：同样参数的多次调用等同于一次调用，应该具有幂等性的是Get、Put、Delete。
• 在函数式语言里，提供一组操作纯函数，这些纯函数由于本身不能持有状态，每次都要求传入所有需要的参数，这些函数也保证：只要传入的参数一样，就一定等得到同样的结果。然而，当函数式语言需要处理有副作用的资源时，就必然要绕弯处理，例如引入monad。
• 在非函数式语言里，如果可以自由写函数的情况下，也会易于提供类似无状态要求的API。

API的设计原则

API设计的时候，要考虑以下几个点：

• 最小暴露原则：只暴露必要的接口，隐藏内部接口。
• 应该针对资源或者算法提供API
• 应该提供对称的一组函数，设计对称API的时候应该考虑不变式，也即，对资源的对称操作所抱持的资源的某种不变的性质。
• 应该提供简洁明了的函数名字
• 应该尽量减少参数个数，只添加必要的参数
  • 有状态的API，应该把一组操作共同依赖的参数作为成员在初始化的时候传入
  • 无状态的API，应该设计合适的共同上下文
• 应该考虑提供怎样的原子操作：例如，是否应该提供批量操作接口，Add和AddRange都提供还是只提供Add，从原子上考虑，像CreateAndXXX这种接口就不应该提供
• 考虑原子的话，那么就可能进一步需要考虑事务，让Begin和End的操作事务化
• 应该考虑接口操作的性质：
  • 幂等性
  • 可重入性
  • 线程安全
  • 并发性
  • 延迟性
• 应该考虑API的同步、异步，并在整个设计里尽量保持一致
• 每组API应该都代表一种Concept，这个Concept应该类似数学的每个概念一样，都有明确的一组性质，例如代数里的Group，拓扑空间，在集合上的定义一种数学概念，这个概念就会符合一些核心的属性
• 如果你有多组API共同协作，它们就会形成一套API，多组API之间应该要有良好的协作构架，就像齿轮
• 可能的情况下让API保持可组合
• 多组API之间尽量要有分层、在层之间做到松耦合，层内做到高内聚
• API应该做到开放封闭，边界要分清。

API的实现要素

API在实现上要考虑

• API的前置假设和后置假设，实现上应该对前假设（例如参数）、后假设（例如返回值）做假设的Check
• API的实现应该考虑关键入口和关键出口的日志
• API的实现应该提供对应的测试，测试是最好的文档
• API的实现应该考虑线程模型

API的用户是程序员

API的用户是程序员，并且API的设计会改变使用API的程序员的思维方式。

API的表达力，可编程能力

一组好的API应该考虑它们被使用时的表达力和编程能力：provides for combining simple ideas to form more complex ideas：

• primitive expressions, which represent the simplest entities the language is concerned with,
• means of combination, by which compound elements are built from simpler ones, and
• means of abstraction, by which compound elements can be named and manipulated as units.

接口设计的原则：单一职责原则

一个接口只干一件事，并把这件事干好，不要干两件事，如果你有复杂的switch-case，基本上你设计接口是设计错了，这个接口不应该干这么多事情，你应该拆分。通过提供一组接口来做，不要用一个函数加一堆flag配置包装一堆子接口。

• 程序员吐槽：我永远不会再为 Oracle 工作了 ！

  • 非常复杂的逻辑、内存管理、上下文切换等，这些都用数千个 flag 连接起来。整个代码充斥着神秘的宏命令，如果不拿出笔记本，并且手动去展开相关的宏命令，就无法理清楚这些命令。甚至可能需要一两天才能真正理解某个宏命令的作用。

  • 有时你需要理顺 20 个不同 flag 的值和效果来预测代码在不同情况下的行为方式。有时多达数百个 flag ！这一点也不夸张。

参考资料

• The Little Manual of API Design
• A Coder’s Guide to Writing API Documentation
• Annoyances of API Design