什么是 REST API？

2025-06-07

什么是 REST API？

如果你看过 Contentful 的文档，你至少会在几个地方看到过 REST 和 API 这两个缩写！但它们到底是什么意思呢？让我们来分解一下。

什么是 API？

API 代表应用程序编程接口 (API)，是不同软件服务之间进行通信的一种方式。在硬件和软件编程中使用不同类型的 API，包括操作系统 API、远程 API 和 Web API（例如 Contentful 提供的 API）。如果您是开发新手，我建议您阅读这篇博文——什么是 API？，以便对 API 和 HTTP 有充分的了解，为本文的讨论做好准备。

whitep4nth3r

什么是 API？

萨尔玛·阿拉姆-内勒 ・ 2021年8月12日

#webdev #javascript #beginners

现在你已经了解了 API 和 HTTP，那么 REST 是如何融入其中的呢？我们来看一下。

REST 是什么意思？

REST 是表述性状态转移 (Representational State Transfer) 的缩写，该术语由美国计算机科学家 Roy Fielding 于 2000 年在其论文“架构风格和基于网络的软件架构设计”中提出。REST 是一组用于创建无状态的基于资源的 Web 服务的规则和指南（我们稍后会对此进行解释）。

您可能会听到 REST API 被描述为 RESTful，或遵循 RESTful 架构。

表述性状态转移规则

让我们来看看 RESTful API 的一些最重要的概念。此列表并非详尽无遗，但旨在概述 REST 架构的设计方式。并非所有 API 都是 RESTful API——有些 API 借鉴了 REST 的原则，但并未完全遵循 REST 的规则。

RESTful API 有一组预定义的可供用户使用的操作

开发人员和文档经常提到“通过 API 公开功能”。API 通常不允许完全控制后端系统。相反，API 会向用户提供预定义的功能和操作。优秀的 API 会附带完善的文档，其中会描述如何以正确的格式发送数据，以及每个 API 功能会返回哪些数据。

新功能通常会使用版本控制系统添加到 API 中，以确保大型应用程序免受潜在重大变更的影响。因此，您最终可能会在应用程序中使用不同版本的 API URL。例如，您可能会在常见情况下看到https://myawesomeapi.dev/api/v1/usersvs。https://myawesomeapi.dev/api/v2/users请注意 URL 之间的区别——/v1 和 /v2。

RESTful API 基于资源

通过 HTTP 进行 RESTful API 调用的响应（通常称为有效负载）会以 HTML、XML、JSON 或类似的文本形式返回，这些资源以存储对象的形式存在。存储对象（或资源）可以是任何内容，例如存储在文档数据库中的博客文章、托管图片的 URL，或存储在关系数据库中多个表中的用户数据。

RESTful API 端点的 URL 格式具有描述性和自文档性。每个 URL（请求资源或请求修改资源）都描述了API 所请求资源的类型。

例如，以下是一个Contentful 内容交付 API (CDA) URL，它通过 HTTP GET 请求获取单个 Contentful 空间的信息。Contentful 空间就像一个存储 Contentful 内容的存储桶，它具有名称和唯一 ID。

注意/spacesURL 的一部分 — — 它定义了我们请求的资源是表示空间的数据。

https://cdn.contentful.com/spaces/{space_id}?access_token={access_token}
Enter fullscreen mode Exit fullscreen mode

该 URL 需要两个动态 URL 参数 —space_id和access_token。space_id是我们希望从数据库获取信息的空间的唯一标识符， 是access_token用于身份验证（稍后我们将讨论 REST API 如何无状态时对此进行详细介绍）。

这是来自Contentful 内容管理 API (CMA)的第二个示例，这次通过 HTTP GET 请求请求空间内可用的指定环境资源（请参阅 URL 中的/environments）。Contentful空间允许多个环境，以便管理应用程序中的内容和功能迁移。此 API 端点接受两个动态 URL 参数 —space_id和environment_id，并且需要通过 HTTP 授权标头发送身份验证令牌。

https://api.contentful.com/spaces/{space_id}/environments/{enviroment_id}
Enter fullscreen mode Exit fullscreen mode

RESTful API 允许读取或修改资源

在上面的示例中，我们使用 HTTP GET 请求从 CDA读取有关 Contentful 空间的信息，并从 CMA读取有关空间内环境的信息。除了检索有关存储资源的信息外，RESTful API 还允许您在单独的 API 调用中创建、更新或删除资源。

使用 CMA，我们还可以使用 HTTP POST、PUT 和 DELETE 方法创建、更新或删除资源。其优点在于，RESTful API URL 不仅以API URL 的格式描述相关资源，还会根据实现的 HTTP 方法描述您在 API 上执行的操作。

在提到 RESTful API 架构时，您可能听说过首字母缩略词CRUD。CRUD代表创建、读取、更新、删除——这些是通过 HTTP 实现的 RESTful API 的标准操作。

现在我们知道了如何从 Contentful API 中读取，让我们看看如何创建、更新和删除。

使用 HTTP POST 创建新环境

使用 HTTP POST 通过 CMA 创建新环境。

向以下 URL 发送 POST 请求：

https://api.contentful.com/spaces/{space_id}/environments
Enter fullscreen mode Exit fullscreen mode

具有以下 HTTP 标头：

Authorization: Bearer <cma_token>
"Content-Type": application/vnd.contentful.management.v1+json
Enter fullscreen mode Exit fullscreen mode

并且您希望在请求正文中创建的环境的名称：

body: {
  "name": "My new environment name"
}
Enter fullscreen mode Exit fullscreen mode

向此 API URL 发送 HTTP POST 请求会创建一个带有自动生成 ID 的新环境。虽然创建带有自动生成 ID 的环境完全没问题，但我们建议您创建带有指定 ID 的环境，以便在自动化脚本中拥有更好的控制力。好消息是，您可以使用 HTTP PUT 请求来执行此操作。

使用 HTTP PUT 创建或更新环境

我喜欢将 HTTP PUT 方法视为将更具体的信息放入数据存储中，而不是通过 POST 发送请求让 API 为我创建一些东西。

要创建具有指定 ID 的新环境，请向以下 URL 发送 HTTP PUT 请求，其中{environment_id}是您想要指定的 ID。

https://api.contentful.com/spaces/{space_id}/environments/{enviroment_id}
Enter fullscreen mode Exit fullscreen mode

使用以下 HTTP 标头：

Authorization: Bearer <cma_token>
"Content-Type": application/vnd.contentful.management.v1+json
Enter fullscreen mode Exit fullscreen mode

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

body: {
  "name": "My new environment name"
}
Enter fullscreen mode Exit fullscreen mode

要更新环境，请进行与上述相同的 API 调用，但要添加一个 HTTP 标头，指定要更新的环境的最新版本，如下所示：

X-Contentful-Version: <existing_version>
Enter fullscreen mode Exit fullscreen mode

使用 HTTP DELETE 删除环境

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

https://api.contentful.com/spaces/{space_id}/environments/{enviroment_id}
Enter fullscreen mode Exit fullscreen mode

并使用以下 HTTP 标头：

Authorization: Bearer <cma_token>
Enter fullscreen mode Exit fullscreen mode

现在，有趣的部分来了！

请注意，使用指定 ID 创建、读取、更新和删除环境的 API URL完全相同！

RESTful API 调用基于单个 URL，该 URL 表示您要创建或修改的资源类型。区别在于，读取方法使用 HTTP GET 请求，创建和更新方法使用 HTTP PUT（根据您要执行的操作使用不同的 HTTP 标头），而删除方法使用 HTTP DELETE。

这就是 RESTful 架构真正闪耀的地方。HTTP 方法与基于资源的 URL 以及不同的 HTTP 标头相结合，使得 RESTful API 的导航和使用非常直观且结构良好。

单击此处查看上面引用的完整 CMA 环境文档。

RESTful API 是无状态的

在此上下文中，“无状态”意味着不同的交互或 API 调用之间不会传递任何信息。在无状态架构中，每个 API 请求都必须仅基于当时随请求发送的信息进行处理。例如，如果您使用身份验证令牌调用 API，则 API 不会记住您在后续请求中已通过身份验证。如果您希望对同一 API 进行更多调用，则必须在所有后续请求中发送身份验证令牌。

您会注意到，上面每个发送给 CMA 的 API 请求都包含一个授权标头。同样，在来自 CDA 的第一个 GET 请求中，身份验证令牌作为 URL 参数传递。

总之

API 是一种使用代码在不同软件服务之间进行通信的方式。REST 是一组用于创建特定类型 API 的规则和指南，并非所有 API 都是 RESTful API。

REST 代表表述性状态转移 (Representational State Transfer)。RESTful API：

  • 为用户提供一组预定义的操作
  • 基于资源
  • 通常允许对资源进行 CRUD 操作 - CRUD 代表创建、读取、更新、删除
  • 无国籍

探索Contentful 文档以巩固您的理解，如果您有任何疑问，请在Twitter上找到我。

文章来源：https://dev.to/whitep4nth3r/what-is-a-rest-api-51h
Devto 翻译
PREV
什么是 API？
NEXT
如何构建仅 HTML 的手风琴 — 无需 JavaScript！