REST API：关键概念、最佳实践和优势

数以千计的公司（从 Google、YouTube 和 Twitter 等科技巨头到初创公司）将他们的业务增长归功于应用程序接口或 API。API 充当机器之间的中间人，使万维网上的数百万客户能够访问各种 Web 产品。

就像餐厅里的服务员接受顾客的点餐，然后将饮料和食物送到顾客面前一样，API也是接收来自应用程序的请求，并返回所需的数据或功能。通常，它们以 REST 风格完成工作。本文概述了什么是 REST，为什么它如此广泛，以及是什么使 API 真正成为 RESTful。

什么是 REST API 及其工作原理

REST 是 Representational State Transfer 的缩写，这是一种用于构建通过 HTTP 协议交互的 Web 服务的架构样式。其原理由计算机科学家 Roy Fielding 于 2000 年制定，因其可扩展性和灵活性，成为了传统机器对机器通信方法的一个广受欢迎的替代方案。它仍然是公共 API 的黄金标准。

REST 客户端可以通过发送 HTTP 请求来与每个资源进行交互

REST API 概念

REST API 范例的关键元素是

• 在用户的计算机或智能手机上运行并启动通信的客户端或软件;
• 提供 API 作为访问其数据或功能的手段的服务器;
• 资源，即服务器可以提供给客户端的任何内容（例如，视频或文本文件）。

为了访问资源，客户端会发送一个 HTTP 请求。作为回报，服务器会生成一个 HTTP 响应，其中包含资源上的编码数据。这两种类型的 REST 消息都是自描述的，这意味着它们包含有关如何解释和处理它们的信息。

REST API 方法和请求结构

任何 REST 请求都包括四个基本部分：HTTP 方法、端点、标头和正文。

HTTP 方法描述要对资源执行的操作。有四种基本方法也称为 CRUD 操作：

• POST 创建资源，
• GET 检索资源，
• PUT 更新资源，使用 PUT
• DELETE 删除资源。

终端节点包含统一资源标识符 （URI），用于指示在 Internet 上查找资源的位置和方式。最常见的 URI 类型是 Unique Resource Location （URL），用作完整的 Web 地址。

标头存储与 Client 端和服务器相关的信息。标头主要提供身份验证数据，例如 API 密钥、安装服务器的计算机的名称或 IP 地址，以及有关响应格式的信息。

正文用于将其他信息传送到服务器。例如，它可能是您要添加或替换的一段数据。

创建新用户的 REST 请求，其中响应将返回已创建资源的 ID。来源：Tableau API

REST 响应结构

作为响应，服务器发送的不是 seek 资源本身，而是它的表示形式 — 对其当前状态的机器可读描述。相同的资源可以用不同的格式表示，但最常用的是 XML 和 JSON。

只要内容相关，服务器就会在响应中包含指向其他相关资源的超链接或超媒体元素。这样，服务器就会给出 Client 端下一步可以做什么以及它可以发出哪些进一步请求的指令。

使用超媒体的自描述性服务器响应的示例。源：劳伦·朗

REST 最佳实践：API 的 RESTful

REST 不与任何特定技术或平台相关联。它也没有规定如何构建 API。相反，它引入了称为约束的最佳实践。它们描述了服务器如何处理请求并响应它们。在这些约束下运行，系统将获得理想的特性。

客户端-服务器自主性

获得的属性：可修改性、更好的系统可靠性

在 REST API 系统中，客户端和服务器使用不同的技术堆栈独立工作。客户端不需要了解任何关于业务逻辑的信息，而服务器对用户界面一无所知。职责分离意味着API提供者和API使用者可以各自进行修改，而不会相互产生不利影响或导致不良后果。

统一接口

获得的属性：易于使用、共同理解

统一接口是区分 REST API 与非 REST API 的关键属性。它规定了与特定服务器进行通信的标准化方法，这种标准化方式不依赖于运行该服务器的客户端应用程序或设备的类型。我们已经提到了支持这种做法的一些基本原则，它们是

• 分配给每个资源的唯一标识符 （URI），
• 解释如何解释它们以及下一步做什么的自描述性消息，
• 能够通过 JSON 或 XML 中的表示形式来操作资源，
• 超媒体链接到相关资源。

无论客户端如何，服务器都使用相同的接口

统一的接口有助于开发人员轻松掌握 API 的逻辑。Envysion 的软件开发总监 Todd Main 承认，如果合作伙伴公司选择了 REST 方法，他会松一口气：“我知道我只需浏览一个对象列表，我通常已经熟悉这些对象，然后查看我可以获得或提供哪些属性。 Todd 补充说，使用 RESTful API 实现代码也很容易：“在我的编程语言中，传递的对象直接转换为数据结构。

分层架构

获得的属性：改进的系统可扩展性和安全性

RESTful 系统具有分层结构，其中每一层独立工作，并且仅与直接连接到它的层交互。调用服务器时，客户端不知道沿途是否有任何中介。

由于采用分层架构，您可以在客户端和服务器之间放置代理或负载均衡器，从而提高可扩展性。将安全性添加为单独的层可增强系统安全性。尽管这些服务负责生成响应，但客户端无需关心接口背后的具体实现细节。

客户端与 API 层交互，通过代理到达服务器

缓存

获得的属性：低服务器延迟、提高应用程序速度和响应能力

REST API 允许客户端在其本地存储经常访问的数据，从而减少重复请求的次数。因此，应用程序进行的调用更少，从而减少了服务器上的负载及其延迟。反过来，应用程序会变得更加响应和可靠。

无状态交互

获得的属性：增强的性能、应用程序可靠性

无状态一词表示 API 不存储与先前会话相关的任何信息，而是独立处理每个请求。有关当前客户端状态的所有数据都包含在请求正文中。

由于REST API是无状态的，因此它无需处理服务器端的状态同步逻辑。会话独立性的另一个优点是任何服务器都可以处理请求。这可以提高应用程序的性能并降低宕机的风险。

“无状态意味着副作用更少，”Hanna Instruments 的开发人员 Pál Váradi Nagy 认为。“例如，在 FTP 中，我们有一个正在进行的会话，其中包含修改会话状态的命令。此状态可能会丢失，有时也会丢失。因此，对于 REST 来说，我们决定尽可能地纯粹。这意味着它依赖于 PURE 函数，当给定相同的输入时，这些函数总是返回相同的输出，并且不会影响其他任何内容。

按需代码 （CoD）

获得的属性：功能定制、扩展功能

服务器可以根据客户端的要求返回一段可执行代码，而不是发回 JSON 表示。CoD 实践让客户对功能有更多控制权，并允许扩展功能。

REST API 原则：业务需求的优先

获得的属性：灵活性

REST仍然与灵活性有关。实施 REST 架构，开发人员可以偏离、扩展或仅部分覆盖其标准约束集。将 so 一个基本约束视为无状态交互。您可以忽略它，转而采用其他机制来在服务器端存储会话信息，以保持应用程序的状态。

这就是为什么你可以听到人们说几乎没有 REST API 真正遵循 Fielding 的工作。

高级软件开发人员兼技术顾问 Garry Taylor 表示：“对我来说，一些约束，比如客户端-服务器架构或无状态，只是很标准且不错的应用程序设计，但另一些约束则是我会极力避免的，就像避开瘟疫一样！特别是，他认为按需代码是个坏主意：‘安全隐患极大，而且服务器必须基于客户端的性质及其执行任何传递代码的能力来做出假设。”

REST API 示例

REST API 概念和原则可能感觉很抽象，直到您尝试使用它们。下面，我们提供了真实 API 的示例，这些 API 将有助于理解 RESTful 方法并了解如何编写 API 文档。

Trello API

一个广泛使用的项目管理工具提供了一个简单的 API，可让您快速了解 REST 资源和应用于它们的 HTTP 方法。

Trello 的 API 介绍提供的第一件事是向他们最基本的资源 — Boards 发出 GET 请求。

使用 cURL 获取 Board 消息 — 一个客户端程序，用于对给定 URL 发出 HTTP 请求

这使您更好地了解如何使用适用于其他基本资源（如 Lists、Cards 和 Actions）的方法进行操作。例如，有两种类型的 POST 请求可用于卡片：

POST /1/cards/[卡片 ID 或短链接]/actions/comments 表示“向卡片

添加评论 POST /1/cards/[卡片 ID 或短链接]/actions/idMembers 表示”向卡片添加成员“

资源的完整列表包含 18 个可通过 API 访问的对象。每个请求都附带详细说明，其中包括所有请求类型的参数和查询示例。

Stripe API

最受欢迎的在线支付解决方案之一可能拥有您可以在 Internet 上找到的最好的 API 文档。Stripe 有一个专门的团队，他们为每个资源编写详尽的指南，其中包含代码片段以及 API 请求和响应的示例。“我们的理念是使文档适应如何使用 API，而不是如何构建，” Stripe 前支付和平台合作伙伴关系主管 Cristina Cordova 解释说。

余额交易的 Stripe Rest API 请求和响应

首先，有一个分步开发快速入门指南。喜欢通过示例学习的工程师可以利用 Stripe Samples。

Twilio API

Twilio 是一个 API 驱动的平台，用于将语音和视频通话以及 SMS、MMS 和其他信息集成到 Web 和移动应用程序中。为了鼓励任何级别的开发人员使用 Twilio 创建通信工具，该公司提出了全面的 REST API 最佳实践。此外，在开始之前，初学者可以阅读有关“什么是 REST API”的简要说明。

Twilio 提供免费试用账户来试用和测试 API 集成。为了更方便，代码片段支持分步指南。

有关如何发送 SMS 的文本说明，并通过 API 请求和 JSON API 响应的示例进行说明

Jira  REST API

Jira 是全球超过 65,000 个团队使用的项目经理中最受欢迎的工具之一。其 REST API 使公司能够以编程方式与仪器交互，将其功能集成到企业软件或其他应用程序中，构建附加组件或自动与 Jira 交互。有一个关于可用资源以及如何通过 API 访问它们的全面指南。

用于创建新 Scrum 板的 Jira REST API 响应

Power BI REST API

据 Gartner 称，Microsoft Power BI 已连续五年在分析和商业智能领域处于领先地位。这个自助服务平台是各行各业的数据分析师、BI 开发人员和决策者的首选。Power BI REST API 套件使所有类型的客户都可以将交互式数据可视化、仪表板和报表直接添加到其现有应用程序中。

在进一步讨论之前，Microsoft 使客户能够探索通过 API 提供的功能。它还提供了一个带有代码编辑器和示例数据的开发人员沙箱。您可以在此处找到有关如何使用 Power BI REST API 的文档。如果您不确定此工具是否满足您的要求，请阅读我们关于 Power BI 优点和缺点的文章。

REST 与其他 API 范例的比较

构建 API 的方法之间的直接比较是值得商榷的。这就是为什么我们选择回顾使 REST 在面向命令的远程过程调用 （RPC）、标准化 SOAP 和基于架构的 GraphQL 中脱颖而出的关键功能。

四种主要 API 范式比较

REST 与 RPC

RPC 已经存在了很长时间，可以公平地认为是 REST 的核心。Pál Váradi Nagy 将 REST 视为“已经发生的事物的受限子集语义 — 远程过程调用”。

RPC 中的过程部分是在 input 上执行函数并返回 output。因此，RPC 在网络上很容易实现，从而获得高性能。这就是为什么它成为了大规模微服务系统的首选，因为它能够促进内部通信的简洁与清晰。RPC 也非常适合 IoT 应用程序，尤其是低功耗应用程序。

最新的 RPC 版本是 gRPC。使用二进制数据而不是文本，其通信比使用 REST 更紧凑、更高效。gRPC 也是类型安全的，这意味着它只会发送预期的数据类型。

但是，gRPC 需要设置客户端 — 将 gRPC 生成的代码合并到客户端进程中。对于构建过程可能不存在的动态语言（例如 JavaScript、Python）来说，这很麻烦。REST 不需要这些。只需在浏览器中键入 URL 即可进行 API 调用。使用浏览器就能轻松测试API的基本功能，这使得测试工作变得非常方便。

此外，REST 允许比 RPC 更好的抽象。遵循 RESTful 约束，您可以尽可能地分离客户端和服务器。RESTful 连接不依赖于预先存在的状态，而 RPC 中没有这样的要求。

请阅读我们的文章什么是 gRPC 以了解更多信息。

REST 与 SOAP

根据 Cloud Elements 的 2017 年 API 集成现状报告，使用 REST 的 API 占 83%，而使用 SOAP 的 API 占 15%。这恰恰证明了 SOAP 还没有消亡。

自 80 年代以来一直从事软件开发的 Rob James 指出，尽管存在缺点，但 SOAP 具有一些重要的优势：“封装比更常见的 REST/JSON 解决方案更容易。Web 服务描述语言（或简称 WSDL，其中编写了 SOAP API 逻辑）提供的信息比典型的 JSON 对象提供的信息多。

SOAP API 与 WS-Security 协议集成，以高级别的隐私和完整性传输消息。这就是为什么它仍然是金融服务、支付网关（PayPal 公共 API）、CRM 软件、身份管理和电信服务的最佳选择。

尽管如此，Rob James 承认他的首选是 REST，因为 SOAP 不容易更改，而且几乎不可能解决：“我遇到过无法使用通用工具解决 WSDL 的情况，因为它是使用特定工具和特定于供应商的标记生成的。

SOAP 主要基于 RPC 的第一个版本 — XML。因此，REST 相对于 XML 绑定的 SOAP 的最大优点是它支持多种格式。

阅读我们的文章 什么是 SOAP 以了解更多信息。

REST 与 GraphQL

要获取其请求的信息，REST API 客户端必须混合和匹配多个终端节点。这滚雪球式地演变成另一个问题 — 数据过度获取，这意味着响应包含不必要的信息。这可能会减慢请求处理速度。

GraphQL 于 2015 年出现，提出了自定义终端节点的新理念。GraphQL API 首先会定义一个架构，这个架构详细描述了数据在服务器上的组织结构。有了这个架构作为基础，客户端就能清楚地知道如何构建查询语句，并准确地获取到所需的响应数据。

移动设备是不可靠的网络。因此，当 RESTful API 必须发出多个请求时，失败的可能性要高得多。这就是为什么 GraphQL 的高效查询与移动 API 非常相关。

RESTful 还是 RESTish，这是个问题

机器对机器交互的基本思想和语义已经存在了很长时间。但是当 REST 出现时，它为 Web API 带来了秩序。

“REST 服务之所以重要，是因为它们尝试标准化接口，”Todd Main 说。他强调，无论是普通的旧 RPC 调用还是 SOAP 都没有这种结构：“这些实际上是远程可用的函数调用。相反，REST 带来了一种更标准的方式，以编程方式浏览系统，或者至少无需在每一步都查阅手册即可与系统交互。

在 RPC 中，URL 表示操作，因为其主要目的是为请求提供服务。REST背后的理念更为宏大——它旨在组织独立系统之间的交互。

REST 的意义远不止使用 HTTP。“您甚至不需要使用 HTTP 来实现 REST 架构，尽管它确实使它变得更容易，”拥有 30 多年编程经验的 Claude Wilbur 说。

但是，如果开发人员无法理解它的整个概念，我们可能会得到比 RPC 多一点的系统，带有 HTTP 动词和漂亮的 URL。没有可缓存性、古怪的约定或零链接来发现下一个可用的操作（超媒体）。意识到这种差异的人将这些 API 称为 RESTish。

另一方面，与 SOAP 不同，REST 不是一个刻板的规范。它在一定程度上实现了标准化，这样的实现可以客观地被称为RESTful。因此，为了安全起见，开发人员可以将其 API 描述为符合 REST 架构，而不是 RESTful。

原文链接：https://www.altexsoft.com/blog/rest-api-design/