一、What's API

作者：忠厚

2022 年 7 月 11 日
本文字数：6134 字
阅读完需：约 20 分钟

API 的英文全拼 application programming interface ，应用程序接口，API 代表应用程序编程接口。这些接口充当软件中介，为应用程序相互交互和对话建立特定的决定和规则。API 指定一个应用程序（网页或移动应用程序）可以向另一个应用程序发出的请求类型，并进一步确定：如何发出这些请求；使用哪些数据格式；以及用户必须遵循的做法。

API 发展历程

API 不是一个新的概念： Linux，Windows，C，Java 都有 API，它们通常被编译成用户的应用程序代码并在用户的计算机中执行。而现在我们讲的 API，更准确地，应称为 Web API，使用 HTTP 协议通过网络调用的 API，虽然 Web API 的历史相对较短，但它们几乎支撑了我们在线业务的方方面面。当您听到首字母缩略词“API”或其扩展版本“应用程序编程接口”时，它几乎就是在指 Web API ，所以我接下来讨论的 API Management，准确的说是 Web API Management。

API 架构风格

架构风格是一组协调架构的约束，这些约束限制了架构组件的特征以及符合该风格的架构组件之间的关系。架构风格是比较抽象的一个词，架构很好理解。风格怎么讲？风格这里我们用生活中穿衣风格来感悟一下，提到正装自然会想到皮鞋/西装，这里正装就是是一种穿衣风格。另外穿西装就一定不可以穿拖鞋吗？答案肯定是可以穿的，但是这样穿很奇怪，会有受到很多人的鄙夷目光，这就是为什么叫 API 架构风格，而不是 API 架构标准，标准通常代表着不遵循标准是行不通的。目前存在多种不同的 API 架构风格，每个架构风格都有它独有的数据交换的模式，以 SOAP/REST/gRPC 应用最为广泛，他们分别代表着昨天、今天和明天。

SOAP

SOAP 是一种基于 XML 格式的、高度标准化的数据交换协议。提起 SOAP 必然要关联到 webservice，webservice 才是一种 API 架构风格，webservice 的三个组成部分:SOAP 是用来描述传递信息的格式， WSDL 用来描述如何访问具体的接口， UDDI 是 webservice 的注册中心，用来管理，分发，查询 webservice。

这种 API 架构风格在企业中真的普遍存在，这证明它曾经流行过，风光过，只是正在慢慢的退出舞台，成为了历史遗留的产物。但是我们依据需要关注它，因为很多场景下我们需要去集成它，对于 Java 项目来说，webservice 开发框架有 Axis2、XFire、CXF 等，但对于其他语言可能没有可复用的框架支持，这是一个问题，需要在技术架构阶段去考虑。比如 GO 就没有现成的框架，需要从底层基于 soap 协议通过 http post 来实现对接。当然还可以通过中间代理去做转换，这个也正是 APIM 里面的一个重要的能力：协议转换。

SOAP 样例

POST /InStock HTTP/1.1 Host: www.example.org Content-Type: application/soap+xml; charset=utf-8 Content-Length: 299 SOAPAction: "http://www.w3.org/2003/05/soap-envelope" <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:m="http://www.example.org">     <soap:Header> </soap:Header>     <soap:Body><m:GetStockPrice><m:StockName>T</m:StockName></m:GetStockPrice></soap:Body> </soap:Envelope>

复制代码

SOAP 的优点

语言和平台无关：支持创建基于 Web 的服务内置功能使 SOAP 能够处理独立于语言和平台的通信，并作出响应。
适用于各种传输协议：SOAP 支持大量传输协议，可以用于多种场景。
内置错误处理：SOAP API 规范可以返回 Retry XML 消息(携带错误码和错误解释)
大量安全扩展：集成了 WS-Security，SOAP 符合企业级事务质量。它为事务提供了隐私和完整性，并可以在消息层面进行加密

SOAP 的缺点

仅支持 XML：SOAP 消息包含大量元数据，且请求和响应仅支持使用冗长的 XML 结构。
厚重：由于 XML 文件的大小，SOAP 服务需要比较大的带宽。
狭窄的专业知识：构建 SOAP API 需要深刻理解各种协议，以及严格的协议规则。
乏味的消息更新：在添加和移除消息属性时需要额外的工作量，这导致 SOAP 的采用率下降。

REST

Rest 出自一篇学术论文中的章节CHAPTER 5 - Representational State Transfer (REST)，学术界的东西都比较广义，学术论文本身也是晦涩难懂的，所以会有各种五花八门的解释。究其核心 Rest 是一种是基于超媒体构建分布式系统的架构风格，是一种面向资源的 API 设计思想和指导原则。遵循这种思想，基于这种原则设计出来的 API，称之为 Restful API。总结下来 REST 是原则，RESTful 是实现。

REST 定义的重要原则

1、REST 是面向资源的，资源是客户端可以访问的任何类型的对象、数据或服务，而资源是通过 URI 进行暴露。

2、REST 使用统一的接口，来解耦客户端和服务实现。本质就是利用 HTTP 本身就有的一些特征，如 HTTP 动词、HTTP 状态码、HTTP 报头等等

3、REST 使用无状态请求模型，此约束使 Web 服务具有高度可扩展性，因为不需要保留客户端和特定服务器之间的任何关联，任何服务器都可以处理来自任何客户端的任何请求

4、REST 由表示中包含的超媒体链接驱动，又叫 HATEOAS，这是客户端和服务端完全解耦的关键，客户端不在写死资源的 URI，而是由服务端动态提供。

2008 年，Leonard Richardson 提出了以下Web API成熟度模型：

Level 0：定义一个 URI，所有操作都是对这个 URI 的 POST 请求。
Level 1：为各个资源创建单独的 URI。
Level 2：使用 HTTP 方法来定义对资源的操作。
Level 3 ：使用超媒体。

根据 Fielding 的定义，级别 3 对应于真正的 RESTful API，也就是 REST 的重要原则在设计实现时我们都满足了，那设计出来的 API 我们才可以说他为一个真正的 RESTful API。根据这个定义 Level 3 级就像是一个完美的女神，想把女神搞到手要先想想需要付出的什么样的成本，是不是有必要，是不是值得。分析之后可能大多数人会发现 level2 级别的女生也很美。我这种屌丝是没搞过 Level 3 级别的 API，哈哈，扯得远了。

REST 的优点

解耦客户端和服务端：REST 的抽象比 RPC 更好，可以更好地解耦客户端和服务端。具有一定抽象的系统可以更好地封装其细节并维持其属性。这使得 REST API 足够灵活，可以在保持系统稳定的同时，随时间进行演化。
可发现性：客户端和服务端的通信描述了所有细节，因此无需额外的文档来理解如何使用 REST API 进行交互。
缓存友好：重用了大量 HTTP 工具，REST 是唯一一种允许在 HTTP 层缓存数据的风格。相比之下，要在其他 API 风格中实现缓存，则要求配置额外的缓存模块。
支持多种数据格式：支持多种格式的数据交互是使 REST 成为当前流行的构建公共 APIs 的原因之一。

REST 的缺点

没有标准的 REST 结构：不存在正确地构建 REST API 的方式。它的大原则容易把握，但是细节不容易做对。
报文较大：REST 基于 HTTP 协议会返回大量元数据，因此客户端可以从响应的信息中了解到应用的状态。在网络传输上会需要更多的带宽资源，这也是 Facebook 在 2012 年推出 GraphQL 风格的主要驱动因素。
过度获取和不足获取问题：由于有时候会出现包含的数据过多或过少的情况，导致在接收到 REST 的响应之后，通常还会需要另一个请求。

参考资料:

microsoft RESTful web API design

RESTful API Design: 13 Best Practices to Make Your Users Happy

gRPC

gRPC 是 Google 开源的一个服务通信框架，它是基于 RPC 的思想打造出的框架，前面的 g，代表是 RPC 中的大哥，龙头老大的意思，另外 g 也有 global 的意思，意思是全球化比较 fashion，是一个高性能、开源和通用的 RPC 框架。这些都是 Google 自己吹出来的，撇开云原生生态体系来看我个人真不觉的这东西有多牛 X，阿里的 Dubbo 比它差吗？关键点在于我们撇不开云原生，如果把 K8S，Istio，Prometheus 这些 CNCF 毕业的明星产品关联起去看，gRPC 代表的正是 API 架构风格的演进方向，gPRC 正在成为云原生里服务通信的标准。

gRPC 的特性

grpc 可以跨语言使用。支持多种语言支持 C++、Java、Go、Python、Ruby、C#、Node.js、Android Java、Objective-C、PHP 等编程语言
基于 IDL ( 接口定义语言（Interface Define Language）)文件定义服务，通过 proto3 工具生成指定语言的数据结构、服务端接口以及客户端 Stub；
通信协议基于标准的 HTTP/2 设计，支持·双向流、消息头压缩、单 TCP 的多路复用、服务端推送等特性，这些特性使得 gRPC 在移动端设备上更加省电和节省网络流量；
序列化支持 PB（Protocol Buffer）和 JSON，PB 是一种语言无关的高性能序列化框架，基于 HTTP/2 + PB, 保障了 RPC 调用的高性能。
安装简单，扩展方便（用该框架每秒可达到百万个 RPC）

gRPC 的优点

简单并且易于理解与开发，gRPC 开发的核心文件是*.proto 文件，定义了 gRPC 服务和消息的约定。根据这个文件，gRPC 框架将生成服务基类，消息和完整的客户端代码。
严格的规范，gRPC 规范是规定有关 gRPC 服务必须遵循的格式，gPRC 在各个平台和实现之间是一致的
高性能，gRPC 消息使用二进制消息格式 protobuf 进行序列化。gRPC 是为 HTTP2 而设计的 HTTP2 具有显著的性能优势。

gRPC 的缺点

浏览器支持有限，gRPC 还不能作为 web api 来使用，gRPC Web 是 gRPC 团队的一项附加技术，gRPC-web 和代理层来执行 HTTP 1.1 和 HTTP 2 之间的转换，它在浏览器中提供有限的 gRPC 支持。
人类不可读，HTTP API 请求以文本形式发送，可以由人读取和创建，这方便了开发人员的理解与集成调试。而 gRPC 消息使用 protobuf 编码不经处理是人类不能看懂的，这代表着 gRPC 的接口作为 OPEN API 开放给第三方使用在现阶段是很不友好的。

参考资料

gRPC.io

gRPC vs REST: comparing APIs architectural styles

HTTP 协议

无论哪种 API 的架构风格其底层的都可以使用 HTTP 协议通信，虽然不仅限于 HTTP，但 HTTP 已经成为了共识。所以对于 HTTP 协议的深入理解是至关重要的。HTTP 协议一个在 ISO 模型中位于应用层的传输协议，人称超文本传输协议，可能大部分程序员们对于 HTTP 的理解仅是客户端向服务端发送一个 get or post 请求，然后服务器端收到了这次请求，写码进行业务处理，最后把处理的结果返回给客户端，这完全没错，这就是 http 协议的本质：请求-响应。但是 HTTP 真的没这麽浅显。这里我不能把所有细节都写出来（我写不出来）,这里我会把与本专栏息息相关的知识点提炼出来概括一下。江湖上关于 HTTP 的文献多入牛毛，但我强烈推荐大家读一下 HTTP 权威指南，构建一个全面的知识体系。

资源 URI URL

资源，所有通过 http 协议请求后返回的东西都叫资源，可以是图片，文档，一段文字，一组数据。
URI，给一个资源发个唯一的编号，这个编号统称为 URI
URL，找到一个 URI 的地址，就叫统一资源定位符，它也是一种标记格式，完整的格式<scheme>://<user>:<password>@<host>:<port>/<path>;<params>?<query>#<frag>

HTTP 报文

报文三部分构成：起始行，报文头，报文体。

请求行（请求报文起始行）：请求报文请求服务器对资源进行一些操作，由请求 Method、URL、HTTP Version 三部分构成,总的来说请求行就是定义了本次请求的请求方式, 请求的地址, 以及所遵循的 HTTP 协议版本
状态行（响应报文起始行）: 响应报文承载了状态信息和操作产生的结果，包含了响应报文使用的 http 版本，数字状态码以及描述操作状态的文本形式的原因短语
报文头：向请求或响应报文中添加一些非常重要的附加信息，通常是 K-V 结构。这部分 http 规范定义了大部分头部属性，应用程序可以随意发明自己所用的头部属性，http 头部分类：通用头部，请求首部，响应首部，实体首部，扩展首部。
报文体：HTTP 要传输的内容，这部分是可选的。可以承载很多类型的数据：图片，视频，文档....

HTTP 报文这部分建议各位老板深入研究一下，毕竟在实际工作中无处不见

连接管理

HTTP 连接是 HTTP 报文传输的关键通道，HTTP 基于 TCP 协议构建，实际上就是在 TCP 可靠连接基础加上一些使用规则，保证了数据有序正确可靠的传输。

HTTP 是如何使用 TCP 连接的
HTTP 要传送一条报文时，会以流的形式讲报文数据的内容通过一条打开的 TCP 连接按序传输。TCP 收到数据流之后，会将数据流堪称被称作段的小数据块，并将段封装在 IP 分组中，通过网络进行传输。所有这些工作都是由 TCP/IP 软件来处理的，对程序员们是透明的，程序员什么都看不到也不需要关注。

HTTP 的连接处理
对于 HTTP 性能而言，网络速度是相对确定的，底层 TCP 的性能是 HTTP 无法干预的，那么 HTTP 对与性能的优化应该怎么做？其对应的方式就是要加快连接处理的方案，减小传输的数据体量，这里先简单概述一下 5 种连接方式。
串行连接：one by one 的方式发起请求。
并行连接：通过多条 TCP 连接，发起并发请求。
持久连接：重用 TCP 连接，以消除连接创建与关闭消耗。
管道化连接：通过共享的 TCP 连接发起并发请求。
多路复用连接（HTTP2.0）：交替传送报文和请求。

客户端识别 &认证

HTTP 最初是一个匿名、无状态的请求/响应协议。web 服务器几乎没有什么信息可以用来判断是哪个用户发送的请求，也无法记录来访用户的请求序列。但是在现代的 web 站点希望能够提供个性化的服务，所以对连接另一端的用户需要更多的了解，便产生了客户端识别这一问题，而 HTTP 并不具有丰富的客户识别能力，发展至今我们有几种方法来应对这一问题，这些方法统一的特点都是将用户相关信息通过 http 头部报文承载。

用户客户端 IP：
cookie:
token:

通过上述的机制我们可以识别出不同的用户，那么这些用户该如何认证？

基本认证：使用用户的 ID/密码作为凭证信息，并且使用 base64 算法进行编码。由于用户 ID 与密码是是以明文的形式在网络中进行传输的（尽管采用了 base64 编码，但是 base64 算法是可逆的），所以基本验证方案并不安全。基本验证方案应与 HTTPS / TLS 协议搭配使用。假如没有这些安全方面的增强，那么基本验证方案不应该被来用保护敏感或者极具价值的信息。
摘要认证：
表单认证：

HTTPS （安全 HTTP）

HTTP 是简单的文本传输协议，且内容是明文传输的，明文数据会经过中间代理服务器、路由器、wifi 热点、通信服务运营商等多个物理节点，如果信息在传输过程中被劫持，传输的内容就完全暴露了。劫持者还可以篡改传输的信息且不被双方察觉，所以 HTTP 协议是不安全的。对于安全要求较高的场景，便产生了 HTTPS 协议。HTTPS 位于 TCP 之上，HTTP 之下，可以简单的理解在 HTTP 准备好报文交给 TCP 处理前，基于 SSL or TLS 进行数据加密，在提交给 TCP 处理。

HTTPS 对话过程中使用的是对称加密还是非对称加密？
我相信大部分人看到这个问题，会直接说出非对称加密。那我成功骗到了你，注意审题。对话过程中使用的是对称加密。因为非对称加密的性能存在问题，所以 https 采用的是非对称加密+对称加密的数据加密机制，使用非对称加密用来获得对称加密的密匙(三个随机数的 SSL 握手阶段)。非对称加密在 https 中只是用来保护对称加密的密匙传输安全。这段话是不是很绕？脑子转起来吧!
客户端如何拿到没有被篡改、掉包的公钥？
在使用 HTTPS 前，需要向 CA 机构申领一份数字证书，数字证书里含有证书持有者信息、公钥信息等，服务器把证书传输给浏览器，浏览器会在本地进行校验看一下证书是否被篡改过，证书就如身份证，证明该公钥对应该网站，没有被掉包。

HTTP2.0

目前存在两大版本，HTTP1.X 与 HTTP2.0 ，国内大部分公司都还在使用 HTTP1.1 协议，在内、外部提供 API 服务。不过很多大型互联网公司都已经有大量的业务线在使用了 HTTP2.0 协议，其核心原因 HTTP2.0 有更好的性能，这里我们先不展开讨论 HTTP2 性能提升的具体细节，在最后章节见。