什么是 REST API？

REST API 是 Web 上最常用的 API 类型。尽管它们无处不在，但开发人员在没有完全理解其本质和工作原理的情况下开始使用它们是很常见的。

本文详细解释了什么是 REST API，并研究了其结构和功能，包括 REST API 端点以及请求与响应的处理方式。通过一些示例，向您展示如何使用 REST API 创建、读取、更新和删除资源。

定义 REST API

REST （REpresentational State Transfer） 是一种用于 Web API 的软件设计模式。REST API 用于允许两个不同的软件相互通信。如果您正在开发自己的软件，并希望将来自第三方服务（甚至您自己的其他服务）的功能集成到您的代码中，那么 REST API 是一种标准方法。

您可以通过 REST API 端点（URL 和 HTTP 方法的组合）向服务发出请求来使用 REST API。您可以使用不同的 HTTP 方法从该服务创建、检索、更新或删除某些数据。

REST API（也称为 RESTful API）遵循以下原则：

• 基于资源：每个请求都应该：
  • 返回相同类型的资源列表
  • 返回单个资源
  • 对资源执行操作（例如 CREATE、DELETE、UPDATE）
• URL 结构统一：例如，调用某个 URL 可能会返回有关 Superman 的信息，而另一个 URL 可能返回 Spider-Man 的信息。）唯一的区别是 ID，但结构相同。
• 接受 HTTP 方法和标头：终端节点接受 HTTP 方法和标头，并返回 HTTP 状态代码（指示成功或错误类型）。
• 无状态：每个 API 调用都独立于之前的调用。如果需要身份验证标头来登录，则在下次调用时必须再次附加该标头。
• 可选超媒体：可以选择包括指向每个资源的相关 API 端点的超媒体链接。虽然在某些情况下超媒体很有用，但尚未被广泛采用，并且大多数 API 不使用此功能。

2000 年，美国计算机科学家 Roy Fielding 在他的论文《 Architectural Styles and the Design of Network-based Software Architectures 》中引入了这种模式，旨在改进现有类型的 API，如 SOAP 和 RPC。从那时起，REST API 已成为大多数 Web 应用程序的标准。

REST API 端点剖析

您可以通过调用终端节点与 REST API 进行交互。这是一个以特定方式构建的 URL，供您与特定服务通信。服务构建其端点的方式存在差异，但通常很容易识别出REST API 端点的主要元素：主机、服务、API 版本、资源类型、资源标识符和任何参数。

并非每个终端节点都会使用所有这些功能。例如，终端节点可能是 RESTful 服务的一部分，该服务不为单个 API 实现单独的服务名称，或者不包含版本号（这对于供内部使用的 API 来说很常见）。

主机： 托管 RESTful 服务的服务器的网络位置。包括协议（HTTP 或 HTTPS）。

服务： 拥有多项服务的公司需要在不同的地址提供每个 API。在上面的示例中，有一个 API（包含用于返回超级英雄列表的终端节点，但也可能包含其他与超级英雄相关的终端节点 — 例如，返回超级英雄宇宙列表的终端节点，例如“Marvel”或“DC”）。除了这个 API 之外，同一提供者还可能提供另一个 API（带有端点 — 可以返回如“Snow White”、“Cinderella”等童话人物的信息）。

API 版本： API 版本用于跟踪对 API 的更改。API 定期更新是正常的，但当出现重大更改时，即需要指定新的 API 版本（例如“v2”）时。用户可以继续调用 “v1” 终端节点，直到他们明确升级到 “v2” 并修复任何重大更改。

资源类型：资源是一系列相关信息。例如，超级英雄资源包含有关特定超级英雄的属性列表，例如他们来自哪里以及他们拥有哪些超能力。终端节点（末尾没有任何资源标识符）是一个列表终端节点，它返回一个超级英雄列表，每个超级英雄都包含一个唯一的资源标识符。

资源标识符：资源标识符是用于检索特定资源信息的唯一标识符，通常位于终端节点 URL 的末尾。例如，如果 Superman 具有唯一 ID “1234”，则调用将返回有关 Superman 的信息。如果您不知道正确的资源标识符，可以通过调用上面的列表终端节点来查找。

查询字符串参数：您还可以在请求信息列表时将查询字符串参数添加到请求的末尾。这些通常用于从结果中对列表进行排序或筛选。在上面的示例中，该参数用于筛选目的：确保仅返回有关特定超级英雄的某些字段。在这种情况下，仅返回 and 字段，并保留其他字段。

REST API 请求剖析

API 端点只是 REST API 请求的一部分。在编写需要与 REST API 交互的代码时，您应该了解请求的四个主要组件：终端节点、HTTP 方法、标头和请求正文。

HTTP 方法

对 REST API 端点的所有请求都包含 HTTP 方法。用于与 REST API 端点交互的最常见方法是：

• POST 创建资源。
• GET 读取资源。
• PUT 更新资源。
• DELETE 删除资源。

例如，要读取 Superman 的记录，您需要向该端点发送 HTTP GET 请求。但是，如果要删除他的记录，您需要向相同的端点（标识资源的 URL）发送 HTTP DELETE 请求。HTTP 方法指示要执行的操作，端点标识操作将受影响的资源。

HTTP 标头

HTTP 标头是随 API 请求一起发送的键值对，用于向服务器提供额外信息。有时它们会自动添加到请求中，但有时您必须自己定义它们。以下是使用 cURL 添加到 API 请求的标头示例：Content-Type

curl -H "Content-Type: application/json" https://example.com/api/

如果您使用 Postman（一个用于测试 REST API 的漂亮图形工具），这可能会自动为您生成一些标头。在下面的示例中，除 1 个标头外的所有标头都是自动生成的：

发送到 REST API 的最常见标头是：

• Content-Type：指定应返回给您的数据格式。常见的选项包括 JSON、XML 和 HTML 等。
• Authorization：许多 REST API 端点需要授权才能使用。如果需要授权，您需要设置相应的标头，并添加正确的身份验证详细信息。请参考 API 文档以了解所需的授权类型以及如何获取身份验证令牌的详细信息。

授权标头的一个示例是 bearer token 选项。如果要向需要不记名令牌的 API 发送请求，可以在标头中发送请求，如下所示：

请求正文

在创建或更新资源时，您需要发送需要存储的任何新数据。这应该在请求正文中发送。您还需要告诉 API 您发送数据的格式 — 例如 JSON。下面介绍如何使用 Postman 发送带有 JSON 正文的 POST 请求，其中包含新的超级英雄超人，并包含与他相关的不同类型的信息。

REST API 响应剖析

REST API 响应应包含：

• HTTP响应代码 —（如200、404或500）允许接收者（通常是前端或后端应用程序）了解他们尝试执行的操作是否成功，以及如果不成功的原因。
• 请求的内容 — 通常为 JSON 格式。

REST API JSON 响应示例

1. GET 返回以下 JSON：

2. POST（以及请求正文中的数据）返回以下 JSON：

3. DELETE（假设此资源存在）返回以下 JSON：

如何使用 RESTful API 创建、读取、更新和删除数据

要完全了解如何使用 REST API 创建、读取、更新和删除数据，可以参考一些具体示例。我们将使用 Contentful API 来逐步引导您完成这些操作。如果您想深入学习，可以免费注册 Contentful。

注册Contentful 帐户并登录后，您将自动进入一个空间，这是一个工作区，您可以在其中编辑要发布到网站和应用程序的所有内容。

要开始与 Contentful REST API 交互，您需要一个用于身份验证的访问令牌。要获取您的访问令牌，请转到“设置”→“CMA 令牌”，然后单击“创建个人访问令牌”。为您的令牌命名，记下它，然后单击 “Generate” 按钮。现在复制您的访问令牌并将其保存在安全的地方。

我们现在要检查您的 API 密钥是否有效。我们建议使用 Postman 来实现此目的。您需要向 CMA 令牌发出 GET 请求并传入“Bearer Token”授权标头，如前所述。

这将返回 a 和一些 JSON。如果您滚动浏览 JSON，您应该能够找到空间的 ID。复制它并将其保存在某个位置，因为您在下一步中会需要它。

使用 HTTP GET 读取资源列表

为了演示如何使用 Contentful REST API，我们将练习读取、创建、更新和删除一些环境。

在 Contentful 中，环境是维护多个内容版本的一种方式。每个帐户都从一个名为 master 的默认环境开始，但很快您将需要创建其他环境，例如沙盒环境，用于测试您希望处理的一些新内容，而不会影响 master 环境。

要从 Contentful 读取环境列表，请向以下对象发送 GET 请求：

https://api.contentful.com/spaces/{space_id}/environments

将 {space_id} 替换为您之前保存的空间 ID，并附加以下 HTTP 标头：

Authorization: Bearer <CMA_TOKEN>

将 <CMA_TOKEN> 替换为您的实际 CMA 令牌。

这将返回一些 JSON，其中包含环境列表和相关信息，以及 OK 状态代码。

使用 HTTP POST 创建新资源

要在 Contentful 中创建新的环境资源，请向以下对象发送 HTTP POST 请求：

https://api.contentful.com/spaces/{space_id}/environments

将{space_id}替换为您之前保存的空间的 ID，并附加以下 HTTP 标头：

Authorization: Bearer <CMA_TOKEN>



Content-Type: application/vnd.contentful.management.v1+json

在请求正文中添加要创建的环境的名称：

body: {



  "name": "My environment name"



}

这将在 Contentful 应用程序中创建一个新环境，您可以通过使用浏览器登录或调用空间的“列表环境”端点来查看该环境：

GET https://api.contentful.com/spaces/{space_id}/environments

当您使用 HTTP POST 在 Contentful 中创建资源时，它将具有自动生成的 ID，或者您可以使用 HTTP PUT 方法自行指定一个 ID 来创建资源。

使用 HTTP PUT 更新资源

我们将使用 HTTP PUT 请求通过更改名称来更新 Contentful 中的环境。为此，请向以下 URL 发送 HTTP PUT 请求，其中 {environment_id} 是要更改名称的环境的 ID，{space_id} 是空间的 ID：

https://api.contentful.com/spaces/{space_id}/environments/{environment_id}

使用以下 HTTP 标头：

Authorization: Bearer <CMA_TOKEN>



Content-Type: application/vnd.contentful.management.v1+json

并在请求正文中发送要创建的环境的名称：

body: {



  "name": "My new environment name"



}

最后，您需要指定要更新的环境版本，方法是添加以下标头，并替换为正确的版本：

<existing_version>



X-Contentful-Version: <existing_version>

请注意，这是 Contentful REST API 特有的功能。在使用其他 REST API 进行更新时，您可能不需要做同样的事情。但是，许多 REST API 添加了与此类似的额外功能，您将在阅读其 API 文档时发现这一点。

如果您不确定最新版本是什么，可以通过向同一终端节点发送 GET 请求来了解，响应会通知您。

使用 HTTP DELETE 删除资源

要删除 Contentful 中空间内的特定环境，请向以下 URL 发送 HTTP DELETE 请求，其中 {space_id} 是空间的 ID，{environment_id} 是要删除的环境的 ID：

https://api.contentful.com/spaces/{space_id}/environments/{environment_id}

并使用以下 HTTP 标头：

Authorization: Bearer <CMA_TOKEN>

REST API 总结

API 是一种使用 JavaScript、PHP、Python、Java、Ruby 和 C# 等编程语言在不同软件服务之间进行通信的方式。REST 是一组用于创建特定类型 API 的规则和准则，并非所有 API 都是 RESTful API。

REST 代表 Representational State Transfer，特点包括：

• 基于资源。
• 结构均匀。
• 接受 HTTP 方法和标头，并返回 HTTP 状态代码作为响应。
• 是无状态的。
• 可以包含超媒体。

浏览 Contentful API 文档以巩固您对 REST API 的理解。

常见问题解答

常见问题解答

REST API 是什么意思？

REST API 是遵循 REST（表示性状态传输）原则的 API，使系统之间能够轻松通信。RESTful 系统在客户端和服务器之间具有分离的关注点，这意味着每个系统都可以彼此独立地实现。REST API 是无状态的，这意味着每个 API 请求都完全独立于任何以前的请求。

REST API 的工作原理是什么？

REST API 向客户端公开端点，允许它们调用服务器。客户端向终端节点发送 HTTP 请求，服务器接收请求。

在大多数情况下，一些身份验证详细信息会随请求一起发送，并且服务器会检查是否允许客户端发出请求。由于 RESTful 系统是无状态的，因此需要对每个请求重新验证客户端。

然后，服务器处理请求并返回响应，通常采用 JSON 或类似格式。它还返回 HTTP 状态代码以通知用户成功或失败。

为什么使用 REST API？

RESTful 服务允许在客户端和服务器之间以及服务器的不同部分之间分离关注点。

REST API 易于使用 — 它们使用 HTTP 调用，这是 Web 的语言。开发人员已经熟悉这一点。

REST API 也是可伸缩的，原因有两个：

• 所有 GET、PUT 和 DELETE 调用都可以缓存（因为它们是幂等的）。
• 服务器运行得更快，因为它们不必存储状态（REST 是无状态的）。

如何找到更多同类API？

幂简集成是国内领先的API集成管理平台，专注于为开发者提供全面、高效、易用的API集成解决方案。幂简API平台可以通过以下两种方式找到所需API：通过关键词搜索API、或者从API Hub分类页进入寻找。

原文链接：https://www.contentful.com/blog/what-is-a-rest-api/