一、What's an API

franciscochonge

What's an API

API的英文全拼  application programming interface ，应用程序接口，API 代表应用程序编程接口。这些接口充当软件中介，为应用程序相互交互和对话建立特定的决定和规则。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](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性能提升的具体细节，在最后章节见。

HTTP/2: the Future of the Internet  这是 Akamai 公司建立的一个官方的演示，用以说明 HTTP/2 相比于之前的 HTTP/1.1 在性能上的大幅度提升。 同时请求 379 张图片，从Load time 的对比可以看出 HTTP/2 在速度上的优势。