API 的亲戚们

前言

为什么会有这篇文章呢？其实算是一个巧合吧！
因为工作的关系，我本来是想找找到底什么是 REST API 的！
但是，看着看着，就看到了“什么是 REST？”、“什么是 RESTful API？”、“什么是 API？”、“什么又是 SDK？”、“什么是 Open API？”等等一堆的问题。
而且之前也确实没有记过这方面的笔记，索性，就全部记下来吧！

^注意：本文主要会以概念解释的方式去介绍各个不同的概念！
^注意：本文采用了大量的网上回答、文章及观点，并根据我自己的一些观点做出了汇总，并不能保证完全正确，但我会尽量将我的想法以及为什么选择 A 而没有选择 B 做出合理的解释！同时，我会给出所有参考资料的链接，有疑惑的可以自行查看！同时，如果有大佬发现我哪里的观点是错误的，还望不吝指正！感谢！

API

API（Application Programming Interface，应用程序接口）是一些预先定义的接口（如函数、HTTP接口），或指软件系统不同组成部分衔接的约定。 用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程，而又无需访问源码，或理解内部工作机制的细节。


—— 百度百科·API

研发人员A开发了软件A，研发人员B正在研发软件B。


有一天，研发人员B想要调用软件A的部分功能来用，但是他又不想从头看一遍软件A的源码和功能实现过程，怎么办呢？


研发人员A想了一个好主意：我把软件A里你需要的功能打包好，写成一个函数；你按照我说的流程，把这个函数放在软件B里，就能直接用我的功能了！


其中，API就是研发人员A说的那个函数。


—— 想问一下什么是API，具体是什么意思？ - 简道云的回答 - 知乎

有一天，轮子哥写了一个专门抓取知乎小黄文的AI，而他每天都会查阅小黄文列表并且点赞。恰好你也是小黄文爱好者，那么轮子哥的账号对你来说就是API接口，你要做的唯一事情就是关注轮子哥账号，每天只需要查阅轮子哥的动态就能看到小黄文，但是不用关心轮子哥到底是用什么方法找到这么多小黄文的。


—— 想问一下什么是API，具体是什么意思？ - PTHFLY的回答 - 知乎

简单来说就是函数。


比如你写了一个库，里面有很多函数，如果别人要使用你这个库，但是并不知道每个函数内部是怎么实现的。使用的人需要看你的文档或者注释才知道这个函数的入口参数和返回值或者这个函数是用来做什么的。对于用户来说 ，你的这些函数就是API。


—— 想问一下什么是API，具体是什么意思？ - 爱要不留余力的回答 - 知乎

SDK

SDK（Software Development Kit, 软件开发工具包）一般是一些被软件工程师用于为特定的软件包、软件框架、硬件平台、操作系统等创建应用软件的开发工具的集合。


—— 维基百科·SDK

通俗点是指由第三方服务商提供的实现软件产品某项功能的工具包。


—— 关于API和SDK的理解及两者区别

最开始的定义就是， api的集合，我们就称之为SDK。


还是拿之前得windows的例子来说，windows提供得所有Api得集合，就称之为 Windows SDK。


然后，随着时间得演化，聪明而又懒惰得程序员们，又给SDK赋予了新的意义。


通过Windows得Api，来开发windows程序是复杂且繁琐得。十分不友好，所以就有了像.Net这样得框架。他封装了底层得Windows Api，然后改造成一组新得，更加易于使用得Api给开发者们使用。


像.Net这种，以一组Api作为输入，以另外一组Api作为输出得中间件，就是现在人们所说得SDK。


—— 什么是SDK

API 和 SDK 的区别

有两套炒菜的机器，都能做酸辣土豆丝，一个叫API，一个叫SDK。


API给了你一个说明书（接口文档），上面说：炒酸辣土豆丝，需要土豆、辣椒、醋、盐。
API上边有几个洞（接口），
第一个洞，扔进去一个土豆（入参），吐出来一个削了皮的土豆（返回值）；
第二个洞，扔进去一个削了皮的土豆，吐出一堆土豆丝；
第三个洞，扔进去一个辣椒，吐出来一堆辣椒丝；
第四个洞，扔进去一些醋和盐，吐出来一份配比好的调料；
说明书上还说了：拿着那些东西，找一口锅，你就能炒出土豆丝了！


SDK呢，只有一个洞。也有个说明书，列出了需要的材料。并且告诉你，只要把这些材料往里一扔，我就能给你一盘酸辣土豆丝！


用户用了之后，反馈给厂家：
SDK确实方便，但是他是咋做的酸辣土豆丝呢？我们看不着啊！
API真麻烦，还得自己去炒！但是我发现，卧槽！用API还能做出炝炒土豆丝！


—— sdk和open api有什么区别？ - 山沟沟儿的回答 - 知乎

Open API

什么是Open API？


所谓（Open API）是服务型网站常见的一种应用，网站的服务商将自己的网站服务封装成一系列API（Application Programming Interface应用编程接口）开放出去，供第三方开发者使用，这种行为就叫做开放网站的API，所开放的API就被称作Open API（开放API）。
OpenAPI的出现一方面是信息联合的需要，另一方面是来自利益驱动。


—— 论Open API的起源与历史

An open API (often referred to as a public API) is a publicly available application programming interface that provides developers with programmatic access to a proprietary software application or web service.
翻译：一个开放的API（通常被称为公共API）是一个对公众开放的应用编程接口为开发人员提供编程访问的专有软件应用程序或Web服务。


In contrast to a private API, an open API is publicly available for all developers to access. They allow developers, outside of an organisation’s workforce, to access backend data that can then be used to enhance their own applications. Open APIs can significantly increase revenue without the business having to invest in hiring new developers making them a very profitable software application. However, it is important to remember that opening back end information to the public can create a range of security and management challenges. For example, publishing open APIs can make it harder for organisations to control the experience end users have with their information assets. Open API publishers cannot assume client apps built on their APIs will offer a good user experience. Furthermore, they cannot fully ensure that client apps maintain the look and feel of their corporate branding.
翻译：与私有API相比，开放的API是公开可用的，供所有开发人员访问。它们使开发人员可以在组织工作人员之外访问后端数据，然后这些数据可用于增强自己的应用程序。开放式API可以显着增加收入，而企业无需投资雇用新的开发人员，使他们成为非常有利可图的软件应用程序。然而，重要的是要记住，向公众开放后端信息会带来一系列的安全和管理挑战。例如，发布开放的API可能会使组织更难以控制最终用户对其信息资产的体验。开放API发布者不能假定基于其API构建的客户端应用程序将提供良好的用户体验。此外，他们无法完全确保客户端应用程序保持其企业品牌的外观。


—— Open API

有两套炒菜的机器，都能做酸辣土豆丝，一个叫API，一个叫SDK。


API给了你一个说明书（接口文档），上面说：炒酸辣土豆丝，需要土豆、辣椒、醋、盐。
API上边有几个洞（接口），
第一个洞，扔进去一个土豆（入参），吐出来一个削了皮的土豆（返回值）；
第二个洞，扔进去一个削了皮的土豆，吐出一堆土豆丝；
第三个洞，扔进去一个辣椒，吐出来一堆辣椒丝；
第四个洞，扔进去一些醋和盐，吐出来一份配比好的调料；
说明书上还说了：拿着那些东西，找一口锅，你就能炒出土豆丝了！


SDK呢，只有一个洞。也有个说明书，列出了需要的材料。并且告诉你，只要把这些材料往里一扔，我就能给你一盘酸辣土豆丝！


用户用了之后，反馈给厂家：
SDK确实方便，但是他是咋做的酸辣土豆丝呢？我们看不着啊！
API真麻烦，还得自己去炒！但是我发现，卧槽！用API还能做出炝炒土豆丝！


不open的API只是放在你自己家的厨房里，只有你自己能用；
open的API呢，放到了大街上，谁都能用！只要每个人在用之前先输入个账号密码，炒菜机的生厂厂家核对一下，对了就能用！


—— sdk和open api有什么区别？ - 山沟沟儿的回答 - 知乎

API的几种设计风格

其实在写这篇文章之前，我就时常会有一些疑惑，比如：REST 和 GraphQL 到底有什么区别？API 到底有哪些种类？
而在写这篇文章的过程中，包括查一些资料的过程中，可以说是越看越迷茫，越查越懵逼！各种答案、回答、文章，包括国内的抄袭、转载的这种风气，实在是让人无法分辨到底哪些答案是正确的！而且在我 Google 了一番之后，发现国外也并没有好到哪里去！有些问题并没有一些准确的答案，让人非常迷茫！
因此，虽然这篇文章中有这一节：API 的几种设计风格，但是我并不能保证这一节的内容是百分百正确的！因为我也正处于一个学习的阶段，一些知识都是从网上汲取来的，因此我只能尽量保证给出我看到的一些还算合理的答案！
不过，所有的观点，我都会给出原文出处！有知道的大佬，希望留言告知！Thanks♪(･ω･)ﾉ

我个人比较赞同的观点是：API 主要有 3 种设计风格：RPC、REST、GraphQL。
和下面的这位博主观点一致：

RPC 说的是本地调用远程的方法，面向的是过程。
REST 形式的 API 组织形态是资源和实体，一切围绕资源。
GraphQL就是面向数据查询。


—— 浅谈三种API设计风格RPC、REST、GraphQL

还有一位博主的观点是：API 主要有 4 种设计风格：RPC、REST、GraphQL、服务端驱动API。
其中 服务端驱动API 是该博主自己总结出的一种风格，如下：

没有高大上的英文缩写，因为这种模式或风格是我自己想出来的，那就是通过API让服务端来驱动客户端，在之前的一些项目中也有过实践。说白了，就是在API的返回结果中包含驱动客户端去怎么做的信息，两个层次：

• 交互驱动：比如包含actionType和actionInfo，actionType可以是toast、alert、redirectView、redirectWebView等，actionInfo就是toast的信息、alert的信息、redirect的URL等。由服务端来明确客户端在请求API后的交互行为的好处是：
  • 灵活：在紧急的时候还可以通过redirect方式进行救急，比如遇到特殊情况需要紧急进行逻辑修改可以直接在不发版的情况下切换到H5实现，甚至我们可以提供后台让产品或运营来配置交互的方式和信息
  • 统一：有的时候会遇到不同的客户端，iOS、Android、前端对于交互的实现不统一的情况，如果API结果可以规定这部分内容可以彻底避免这个问题
• 行为驱动：更深一层的服务端驱动，可以实现一套API作为入口，让客户端进行调用，然后通过约定一套DSL告知客户端应该呈现什么，干什么。
  
  

之前有两个这样的项目采用了类似的API设计方式：

• 贷款审核：我们知道贷款的信用审核逻辑往往会变动比较大，还涉及到客户端的一些授权（比如运营商爬虫），而且App的发布更新往往比较困难（苹果App Store以及安卓各大应用商店的审核问题）。如果采用服务端驱动的架构来告知客户端接下去应该呈现什么界面做什么，那么会有很大的灵活性。
• 客户端爬虫：我们知道如果采用服务端做爬虫很多时候因为IP的问题会被封，所以需要找很多代理。某项目我们想出了客户端共享代理的概念，使用手机客户端来做分布式代理，由服务端驱动调度所有的客户端，那么这个时候客户端需要听从服务端的指示来做请求然后上报响应。
  
  

一般而言，对外的Web API是不会采用这种服务端驱动客户端的方式来设计API的。对于某些特殊类型的项目，我们可以考虑采用这种服务端驱动的方式来设计API，让客户端变为一个不含逻辑的执行者，执行的是UI和交互。


—— API设计风格（RRC、REST、GraphQL、服务端驱动）

对于该博主的观点，我本人并不太赞同，虽然 服务端驱动 API 这种想法确实很有意思，但是我总感觉这个东西只能算是一个变种，相当于把客户端和服务端的位置调了一下，或者说两端同时充当服务端和客户端。

乍一看，还和 WebSocket 有些像，而且 REST API 似乎也有这样类似的功能，如果深挖一下，肯定也能做到该博主说的这种 Case。因此，我觉得这种可以作为一个变种，并不能算是一种 API 风格。

不过，对于该博主的这种观点，我在另一篇文章中也看到了同样的分法，但是那篇文章的作者并没有说明是吸取的该博主的观点还是从哪里看到的权威分法。而且那篇文章我找不到了，查的文章有点多，一不小心关掉了，就再也找不到了。

当然，以上观点仅是本人的看法及观点，对原文博主并无恶意，不喜勿喷！如果有不同看法或观点，欢迎评论区探讨，大家一起进步！或者如果知道有权威的分类，希望能不吝告知！不胜感激！

当然了，也不是只有以上的两种分法，在几篇英文的文章中，我还看到了另一种分法：REST、RPC、SOAP。
—— Different API Types

但是，个人认为，这是不正确的，SOAP 应该是属于 RPC 的一种，不能与 RPC 作为同级。具体原因，可以看下面几节。

RPC

在网络世界里，不同机器要怎么互相通信？最基础的方法是基于 TCP/IP 通过 Socket 编程去实现调用方和被调用方。但是 Socket 编程的难度大，需要比较强的专业性，实现又复杂，如果每一次机器之间要通信时，程序员都要手动去处理这么多，这就让新手能做的，变成了要精通网络的老师傅才能完成。有没有什么更好的办法呢？


在 1984 年，Bruce Jay Nelson 发表了奠定基础性的论文 Implementing Remote Procedure Call，定义了机器之间互通这种远程调用的标准。RPC (Remote Procedure Call) 即远程过程调用，有了它，客户端可以像调用本地接口一样调用远程的服务端。



—— 浅谈 RPC 和 REST: SOAP, gRPC, REST

RPC（Remote Procedure Call）— 远程过程调用，是一个很大的概念, 它是一种通过网络从远程计算机程序上跨语言跨平台的请求服务，rpc能省略部分接口代码的开发，可以跨机器之间访问对象(java rmi)，可以有更方便的加密和更高效的数据传输性能, 而不需要了解底层网络技术的协议, RPC不仅可以走HTTP/HTTPS, 也可以自定义 tcp 协议, 从而省略HTTP繁杂的规则和冗余信息。


—— RPC体系,RPC和WebService的区别详解

RPC（Remote Procedure Call Protocol）——远程过程调用协议，它是一种通过网络从远程计算机程序上请求服务，而不需要了解底层网络技术的协议。RPC协议假定某些传输协议的存在，如TCP或UDP，为通信程序之间携带信息数据。在OSI网络通信模型中，RPC跨越了传输层和应用层。RPC使得开发包括网络分布式多程序在内的应用程序更加容易。
RPC采用客户机/服务器模式。请求程序就是一个客户机，而服务提供程序就是一个服务器。首先，客户机调用进程发送一个有进程参数的调用信息到服务进程，然后等待应答信息。在服务器端，进程保持睡眠状态直到调用信息到达为止。当一个调用信息到达，服务器获得进程参数，计算结果，发送答复信息，然后等待下一个调用信息，最后，客户端调用进程接收答复信息，获得进程结果，然后调用执行继续进行。


—— SOA,SOAP,RPC,以及 RPC协议与 REST 协议之间的关系(搜狗)

当客户端的应用想发起一个远程调用时，它实际是调用客户端的 Stub。它负责将调用的接口、方法和参数，通过约定的协议规范进行编码，并通过本地的 RPCRuntime 进行传输，将调用网络包发送到服务器。服务器端的 RPCRuntime 收到请求后，交给服务器端的 Stub 进行解码，然后调用服务端的方法，服务端执行方法，返回结果，服务器端的 Stub 将返回结果编码后，发送给客户端，客户端的 RPCRuntime 收到结果，发给客户端的 Stub 解码得到结果，返回给客户端。


—— RPC原理以及GRPC详解

RPC(Remote Procedure Call)：远程过程调用，它是一种通过网络从远程计算机程序上请求服务，而不需要了解底层网络技术的思想。
RPC 是一种技术思想而非一种规范或协议。【作者说：这句我觉得非常正确！✅】


—— 花了一个星期，我终于把RPC框架整明白了！

几种 RPC 框架/协议

• 阿里的 Dubbo/Dubbox
• Google gRPC
• SOAP（Simple Object Access Protocol，简单对象访问协议）

以上列出的并不是所有，也不是使用最多的、或者说常见的、常使用的！
仅仅是在查资料的过程中碰到了很多文章都谈到 gRPC、SOAP 这些一脸看去非常令人懵逼的缩写，因此在这里简单列出来，做些简单的了解！

Alibaba Dubbo(Apache Dubbo)

Dubbo是阿里巴巴开源的基于 Java 的高性能 RPC（一种远程调用） 分布式服务框架（SOA），致力于提供高性能和透明化的RPC远程服务调用方案，以及SOA服务治理方案。
Dubbo 使用的是 RPC 通信，而Spring Cloud 使用的是HTTP RESTFul 方式。


—— Dubbo

回顾 Dubbo 社区过去一年的发展，其中一个重要的节点就是 2019 年 5 月从 Apache 孵化毕业，成为第二个由 Alibaba 捐献后从 Apache 毕业的项目，我有幸参与到了从重启开源、进入 Apache 孵化到毕业的整个过程。社区在此过程中做了大量的工作，包括邮件列表建设、代码规范检查、文档和代码国际化、issue/pr 处理等，这些一方面是 Apache 社区要求的工作，同时也为推动 Dubbo 的发展起到了正面的作用。


在从 Apache 毕业之后，Dubbo 相关的项目也进行了迁移，都迁移到了 github.com/apache 组织之下。


—— 回望 Apache Dubbo 这一年走过的路

对于 Dubbo 仅做最基础的了解，本文并不深入探究 Dubbo。

gRPC

gRPC is a modern, open source, high-performance remote procedure call (RPC) framework that can run anywhere. gRPC enables client and server applications to communicate transparently, and simplifies the building of connected systems.
翻译：gRPC是可以在任何地方运行的现代，开源，高性能远程过程调用（RPC）框架。 gRPC使客户端和服务器应用程序可以透明地进行通信，并简化了连接系统的构建。


—— Github - gRPC

gRPC：是 Google 公布的开源软件框架，基于HTTP 2.0 协议，并支持常见的众多编程语言。RPC 框架是基于 HTTP 协议实现的，底层使用到了 Netty 框架的支持。


—— 花了一个星期，我终于把RPC框架整明白了！

像 SOAP 这类基于文本类的 RPC 框架，速度上都是有先天不足的。为了有比较好的性能，还是得用二进制的方式进行远程调用。gRPC 是现在最流行的二进制 RPC 框架之一。2015 年由 Google 开源，在发布后迅速得到广泛关注。


gRPC 的协议是 Protocol Buffers，是一种压缩率极高的序列化协议，效率甩 XML，JSON 好几条街。Google 在 2008 年开源了 Protocol Buffers，支持多种编程语言，所以 gRPC 支持客户端与服务端可以用不同语言实现。


gRPC 更多的是用在微服务集群内部，服务与服务之间的通信，服务与客户端之间的通信，REST 可以说是现在的主流。


—— 浅谈 RPC 和 REST: SOAP, gRPC, REST

SOAP(Simple Object Access Protocol，简单对象访问协议)

SOAP（原为Simple Object Access Protocol的首字母缩写，即简单对象访问协议） 是交换数据的一种协议规范，使用在计算机网络Web服务（web service）中，交换带结构的信息。SOAP为了简化网页服务器（Web Server）从XML数据库中提取数据时，节省去格式化页面时间，以及不同应用程序之间按照HTTP通信协议，遵从XML格式执行资料互换，使其抽象于语言实现、平台和硬件。


—— 维基百科 - 简单对象访问协议

RPC 是远程调用，有多种方式实现，基本上包含了传输方式和对象反序列化序列化方式的组合。


SOAP 只是其中的一种方式，基于http传输约定格式的xml, 用wsdl描述，由于比较啰嗦，之前在企业应用的比较多，互联网上已经用的比较少了，一般用json over http的restful比较多，还有一些追求效率更高的rpc方式连http也不用，用另外的编码方式的数据直接走socket，比如thrift, protobuf之类。


—— rpc和soap有什么区别呢？ - Paco Li的回答 - 知乎

所有的远程服务调用都叫做rpc，soap是使用基于 XML 的协议通过http来实现rpc的一种方式。


—— rpc和soap有什么区别呢？ - 左利手的回答 - 知乎

在上面列出的一些，以及没有列出的一些文章或回答中，我看到很多种关于 SOAP 的说法，有将其作为与 RPC 同级的，也有认为其是基于 RPC 思想实现的一种协议的。

但是，本人观点是：RPC 是一种远程调用的技术思想，而 SOAP 是以 RPC 思想为指导，使用 HTTP 传输的 XML 格式的一种文本型 RPC 实现。

REST

REST 的全称是 Representational State Transfer，即表述性状态转移^{这几个单词有好多中文翻译，意思意思就可以了}，Roy Fielding博士在2000年他的博士论文中提出来的一种软件架构风格。


—— REST与RESTFul API

REST的定义
OK，现在让我们来看看REST的定义。Wikipedia是这样描述它的：

Representational State Transfer (REST) is a software architecture style consisting of guidelines and best practices for creating scalable web services. REST is a coordinated set of constraints applied to the design of components in a distributed hypermedia system that can lead to a more performant and maintainable architecture.

从上面的定义中，我们可以发现REST其实是一种组织Web服务的架构，而并不是我们想象的那样是实现Web服务的一种新的技术，更没有要求一定要使用HTTP。其目标是为了创建具有良好扩展性的分布式系统。


反过来，作为一种架构，其提出了一系列架构级约束。这些约束有：

1. Client–server 【客户-服务器模型】
2. Stateless – Each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client.
   【从客户端到服务器的每个请求必须包含理解该请求所需的所有信息，并且不能利用服务器上存储的任何上下文。因此，会话状态完全保留在客户端上。】
3. Cacheable – Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests.
   【缓存约束要求对请求的响应中的数据被隐式或显式标记为可缓存或不可缓存。 如果响应是可缓存的，则授予客户端缓存以将响应数据重新用于以后的等效请求的权限。】
4. Uniform interface 【一个REST系统需要使用一个统一的接口来完成子系统之间以及服务与用户之间的交互。这使得REST系统中的各个子系统可以独自完成演化。】
5. Layered system – The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot “see” beyond the immediate layer with which they are interacting.
   【分层的系统样式允许通过限制组件的行为来使体系结构由层次结构层组成，从而使每个组件都无法“看到”与组件交互的直接层。】
   【在一个REST系统中，客户端并不会固定地与一个服务器打交道。】
6. Code on demand (optional) – REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This simplifies clients by reducing the number of features required to be pre-implemented.
   【REST允许通过下载和执行小程序或脚本形式的代码来扩展客户端功能。通过减少预先实现的功能数量，简化了客户端。】
   
   
   —— What is REST

—— REST简介

说实话这样解释是比较令人懵逼的，包括我自己写到这里的时候都愣了一下，明明最开始看资料的时候觉得对 REST 的概念已经很清楚了呀！那为什么这一刻我又懵了呢？
归根结底，还是并没有彻底理解导致！于是我又再次思考了一番，想到了一个这样的例子：

我身为一个厨师，想要做一盘土豆丝，但是当前年代(假设时间比较久远)的土豆丝口味/做法太low了，于是我自己设计了一种新的土豆丝口味/做法，我将这种口味/做法命名为酸辣！而别人想要按照我设计的这种口味/做法做出一盘酸辣土豆丝，就需要满足几个条件：

1. 土豆必须切成丝
2. 必须是辣的
3. 必须是酸的
4. …………

类比到 REST，如下：

我身为Roy Fielding博士，想要做一款软件(为了博士毕业？)，但是当前年代(自己想)的软件架构风格太low了，于是我自己设计了一种新的软件架构风格，我将这种软件架构风格命名为REST！而别人想要按照我设计的这种架构风格做出一款软件，就需要满足几个条件：

1. Client–server
2. Stateless
3. Cacheable
4. Uniform interface
5. Layered system
6. Code on demand (optional)

因此，REST 就是一种软件架构风格，要遵循该风格设计软件，需要满足一些约束。

REST API 与 RESTFul API

REST API是一组关于如何构建Web应用程序API的架构规则、标准或指导，或者说REST API是遵循API原则的一种架构风格。


REST API是Web API设计的一种规范或者指导原则，而RESTful API则是这中架构设计原则或者规范的一种具体实现方式。也就是说，RESTful API是REST API的非正式实现方式，因为实现REST API的方式有很多，RESTful API只是其中一种，且没有完全满足REST API的所有设计原则，每个开发者在实现REST 架构时的则重点都会有差别。


—— 正确甄别API、REST API、RESTful API和Web Service之间的异同

如果一个系统满足了上面所列出的五条约束，那么该系统就被称为是RESTful的。


—— REST简介

作为当前时间段最流行的 API 风格，REST API 不敢说家喻户晓，但至少或多或少都知道一些关于。
那么，REST API 和 RESTFul API 到底有什么区别呢？虽然上面的这两段截取内容都做出了一定的说明，但是似乎并不很清晰啊！
看下面这个(沿用上面的土豆丝例子)：

作为一个厨师，我设计了一种新的土豆丝做法，叫“酸辣”！然后呢，经过一段时间的传播，这种新做法在全球范围内都火了，大家都知道了“酸辣”这个词，茶余饭后都会谈到这个新颖的做法，“酸辣”怎么怎么了…、“酸辣土豆丝”怎么怎么了…
但归根结底，人们谈论的“酸辣”、“酸辣土豆丝”，都是在谈论我设计的这种新做法！


但法外狂徒张三就不一样了，刚打完疫苗，张三来到一家饭店，结果好巧不巧，叫了一盘土豆丝，张三一尝，咦？居然是酸辣味的！张三说：“这个酸辣味的土豆丝真好吃，这厨师真厉害啊！于是，狼吞虎咽，吃的干干净净！”
从张三的行为中可以看到，张三对“酸辣土豆丝”的关注重点在于“土豆丝”，即便这个“土豆丝”是“酸辣的”，但还是掩盖不了它是一盘“土豆丝”的事实，是用来吃的！

类比到 REST 上，我们再来一遍：

作为一个博士，Roy Fielding 设计了一种新的 API 风格(软件架构风格)，叫“REST”！然后呢，经过一段时间的传播，这种新风格在全球范围内都火了，大家都知道了“REST”这个词，茶余饭后都会谈到这个新颖的风格，“REST”怎么怎么了…“REST API”怎么怎么了…
但归根结底，人们谈论的“REST”、“REST API”，都是在谈论 Roy Fielding 设计的这种新风格！


但法外狂徒张三就不一样了，刚吃完土豆丝，张三回到了办公室，准备看看从客户手里刚拿到的代码，结果好巧不巧，看到一堆“API”，张三细一看，咦？居然是“RESTFul的”！张三说：“这个 RESTFul API 真好用，Roy Fielding 真啊！于是，如痴如醉，逐字逐句，将 API 搞的明明白白！”
从张三的行为中可以看到，张三对“RESTFul API”的关注重点在于“API”，即便这个“API”是“RESTFul”的，但还是掩盖不了它是一堆“API”的事实，是用来衔接软件系统的不同组成部分的！

个人觉得，看完上面的小故事，应该会清晰很多吧！
REST API 几乎可以与 REST 划等号，也没人会在这两个词上去纠结；
而RESTFul API 则是形容该 API 是 RESTFul 的，是遵循了REST 架构风格的约束条件，而设计的一种 API。

RESTFul API

上面已经介绍了 RESTFul API 了，为什么还要再有一节呢？
其实我的本来意图是这样的，结果…唉，说多了都是泪啊！

我们前面有提到，REST 架构风格有一些约束条件，而遵循 REST 风格，满足了这些约束条件的 API 叫做 RESTFul API。
但是，REST 的约束并没有过于具体，仅表现在概括性的层面上，比如：无状态、统一接口等，并没有约束怎么去实现无状态，怎么实现统一接口。
因此，RESTFul API 的实现方式并不统一，可以有多种多样的实现。
也就是说，

RESTful API 是 REST API 的非正式统一实现方式或规范。


—— 正确甄别API、REST API、RESTful API和Web Service之间的异同

但是，即便如此，在设计 RESTFul API 的时候，我们也需要尽可能遵循一些好的实践：

1. RESTFul API 基于“资源”，数据也好、服务也好，在 RESTFul API 里一切都是资源。REST提倡所有的接口都是基于资源的，所有的增删改查操作都是对于资源状态的改变。【这也是 REST 中“状态转移”的由来】
2. 无状态。一次调用就返回结果，不存在类似于“打开连接-访问数据-关闭连接”这种依赖于上一次调用的情况。
3. 使用 JSON 描述数据（使用 JSON 格式返回数据）。
4. URL 中通常不出现动词，只有名词。
5. 使用HTTP动词来操作资源，描述对资源状态的增删改查。
   GET：查询 - 【比如： GET /users/1 获取 id 为 1 的 user 的信息】
   POST：新增 - 【比如：POST /users 创建一个新的 user】
   PUT：更新 - 【比如：PUT /users/1 修改 id 为 1 的 user 的信息】
   DELETE：删除 - 【比如：DELETE /users/1 删除 id 为 1 的 user】
6. 对每一个 HTTP 请求的相应结果都要指明一个状态码。
   200：查询操作 GET 请求成功
   201：POST 创建资源成功
   202：PUT 更新资源请求成功【在 HTTP 中 202 代表：ACCEPTED，该请求已被接受进行处理，但是处理尚未完成】
   400：参数错误
   401：没有访问权限
   403：访问的资源被禁止了
   404：当前请求的资源没有找到
   500：未知错误 / 服务器内部错误
7. 【除状态码外，出现错误时，最好也返回一个错误码及错误信息，可以提升一定得用户体验】
8. API 必须有版本的概念，实现对版本控制的支持，如：v1、v2、v3等。
9. 在 RESTFul API 使用 Token 来授权和验证身份，而不是 Cookie。^{【今天好像看到一篇文章说很多大厂因为用户隐私的问题，决定要放弃 Cookie 了，也不知道是真是假】}
10. URL 中大小写不敏感，不要出现大写字母，使用 - 而不是使用 _ 做URL路径中字符串连接。
11. URL 中资源列表用【/resources】，单个资源用【/resources/:id】
    比如：Github - List branches: GET /repos/{owner}/{repo}/branches
    比如：Github - Get a branch: GET /repos/{owner}/{repo}/branches/{branch}
12. 有一份漂亮的文档【很重要】
    
    

—— REST与RESTFul API最佳实践
—— REST与RESTFul API

Swagger

在查找有关 REST 的资料时，看到很多文章中都提到了 Swagger，而且我个人比较喜欢 Java，之前也见过很多次 Swagger，隐约知道这是个做 API 文档的东西，但并没有详细了解过，因此在这里也记录下。

Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset.
翻译：借助Swagger开源和专业工具集，为用户，团队和企业简化API开发。


—— Swagger - 官网

Swagger 是什么？

1. 是一款让你更好的书写API文档的规范且完整框架。
2. 提供描述、生产、消费和可视化RESTful Web Service。
3. 是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。
   
   

—— swagger 介绍及两种使用方法

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是 Swagger 的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。


—— Swagger介绍及使用

简单来说，Swagger 就是一个用来描述和生成 RRESTFul API 接口文档的工具集，而这个工具集定义了一些约束，也就是所谓的规范。

OpenAPI 与 OAS

在看 Swagger 的时候看到很多文章中提到了 OpenAPI 与 OAS 这个词，但是 OpenAPI 这个词前面不是已经说了吗？怎么又有一个 OpenAPI？怎么回事？
还有，OAS 是个啥？和 SOAP 有关系吗？什么关系？

事实上，此 OpenAPI 非彼 Open API！OAS 和 SOAP 也半毛钱关系都没有！

我们说了，Swagger 是一个用于描述和生成 RESTFul API 接口文档的工具集，而这个文档，到底怎么写，或者怎么配置，以便 Swagger 自动生成呢？Swagger 有一个自己的规范，叫 Swagger Specification（Swagger 规范）。
2015年11月，Swagger Specification 被捐赠给了一个叫做 OpenAPI Initiative 的新成立的组织，并在2016年1月更名为 OpenAPI Specification，也就是 OAS。
而这个规范，也就是 OAS 的第二版也被命名为 OpenAPI 2.0，最新的第三版叫 OpenAPI 3.0。
我们见到的 OpenAPI 就是指的 OAS，也就是 OpenAPI 规范。
^{不过，我在 Swagger 官网看到的名字确实 OAS 2.0，OAS 3.0 这样的！不过，无所谓了，只要我们知道这是个啥就可以了！}

—— 使用 OAS（OpenAPI标准）来描述 Web API
—— OpenAPI Specification

GraphQL

GraphQL 这几年很火，大有一种要干翻 REST 的趋势，当然，到底干不干得翻，那谁知道呢！
不过，即便如此，也掩盖不了 GraphQL 火起来了的事实，那么，到底什么是 GraphQL 呢？

GraphQL 是由 Facebook 创造的用于描述复杂数据模型的一种查询语言。这里查询语言所指的并不是常规意义上的类似 SQL 语句的查询语言，而是一种用于前后端数据查询方式的规范。


—— GraphQL简介及入门

等等，前后端数据查询？我们不是已经有 REST 了吗？用起来非常好用啊！

其实不然，有人觉得 REST 好用，也用人觉得 REST 太过繁琐！

2、RESTful存在的问题

RESTful是我们已经很熟悉的用于api通信的规范，如这样：

GET http://127.0.0.1/user/1 #查询
POST http://127.0.0.1/user #新增
PUT http://127.0.0.1/user #更新
DELETE http://127.0.0.1/user #删除

在查询的时候，往往是这样：

#请求
GET http://127.0.0.1/user/1
#响应：
{
 id : 1,
 name : "张三",
 age : 20,
 address : "北京市",
 ……
}

这样似乎是没有问题的，如果，对于这次请求，我只需要id和name属性，其他的属性我都不需要，如果我依然拿到的是全部的属性，这是不是一种资源浪费？还有这样的一种场景，就是一次请求不能满足需求，需要有多次请求才能完成，像这样：

#查询用户信息
GET http://127.0.0.1/user/1
#响应：
{
 id : 1,
 name : "张三",
 age : 20,
 address : "北京市",
 ……
}
#查询用户的证件信息
GET http://127.0.0.1/card/8888
#响应：
{
 id : 8888,
 name : "张三",
 cardNumber : "666666666666",
 address : "北京市",
}

查询用户以及他的信息，需要进行2次查询才能够完成，这样对于前端等接口的使用方是很不友好的，试想一下，如果查询信息有10个，是不是要发起10次请求才能完成？

3、了解GraphQL优势

GraphQL很好的解决了RESTful在使用过程中的不足，接下来，我们进一步了解下它。

3.1、按需索取数据，避免浪费

示例地址：http://graphql.cn/learn/schema/#type-system


可以看出，当请求中只有name属性时，响应结果中只包含name属性，如果请求中添加appearsIn属性，那么结果中就会返回appearsIn的值。

3.2、一次查询多个数据

可以看到，一次请求，不仅查询到了hero数据，而且还查询到了friends数据。节省了网络请求次数。


—— GraphQL简介及入门

用前面引用过的几句话来说：

REST 形式的 API 组织形态是资源和实体，一切围绕资源。
GraphQL 就是面向数据查询。【可以根据需要，自由组合数据结构】


—— 浅谈三种API设计风格RPC、REST、GraphQL

其它的一些相关词

在查以上的资料时，我还见到了一些比较独立的词，也有可能并不独立，只是我水平不够，关联不到一起！不过，不管怎样，还是记一下的好！

SOA

面向服务的架构（service-oriented architecture，SOA）是一个组件模型，它将应用程序的不同功能单元（称为服务）进行拆分，并通过这些服务之间定义良好的接口和协议联系起来。接口是采用中立的方式进行定义的，它应该独立于实现服务的硬件平台、操作系统和编程语言。这使得构建在各种各样的系统中的服务可以以一种统一和通用的方式进行交互。


—— 百度百科 - SOA （面向服务的架构）

简单来说，SOA 是一种架构设计模式，它的思想在于，将业务拆分成独立的服务，提供给多个组件，使整个软件体系可重用、可扩展、易维护。

同时，针对 SOA,有一个比较好的知乎回答，相信看完这个回答，应该会对 SOA 有个较为清晰的认知：

• 如何通俗易懂地解释什么是SOA？

后记

这篇文章前前后后加起来，足足花费了一周多的时间，虽然都是在下班后写一写，但是也足以见得这篇文章的“分量”了吧！
当然，并不敢说我的文章写的有多么得对，多么正确，观点一定权威，但至少，在我看来，至少有个可以说服人的理由吧！
最后，实在不想说太多了，实在是把我写得够够的了！

【如有侵权，请联系我！】
【如有谬误，欢迎指正！】