第一章介绍了什么是 API,RPC 和 REST 的优缺点,以及设计良好的 API 应该是什么样的。
什么是 API
本书所指的 API 仅指 Web API,作为一个黑盒,提供给用户调用。不同于普通的库,API 的提供方 可以对 API 内部的行为有着绝对的控制,同时也无需暴露背后消耗的资源。
RPC 与 REST
首先需要介绍 stateless 和 stateful。
stateless 指每一次调用,只要参数相同,就会得到相同的结果,与其他请求无关。而 stateful 则 会依赖于存储的数据,之前的调用结果等等,因此每次调用得到的结果不尽相同。
RPC(remote procedure call),命名方式为具体描述调用后执行的内容,例如 showFlightNum
,
bookFlightTicket
,更适合描述 stateless。
REST(不是 RESRful)则是以资源为中心,描述对具体资源的操作,一般为操作 + 资源,
<Method> + <Resource>
,更适合描述 stateful。
什么是一个良好设计的 API
- 需要能够很好地完成用户的需求,即需要找到那些隐性要求,如调用时长,正确率等等。
- 需要尽可能提供完善的功能,否则用户可能会通过一些非常规手段实现这些功能。
- 接口要在为普通用户提供方便的同时,也要能满足部分高级用户的需求,例如添加可选参数。
- 各个接口所需的参数名称应该具有一致性,方便调用者在不参考文档的情况下调用。

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.