了解 REST API - 不耐烦者指南

我的文章在这里交叉发布

REST（Re演示 State T传输）API 是现代 Web 开发的支柱。本文将详细介绍如何创建和使用现代 REST API、制作 API 时要考虑哪些设计决策以及作为 REST 基础的理论。

实用指南

本节深入探讨如何将 REST API 与 HTTP 结合使用，涵盖端点、方法、请求和响应。您将找到开始进行 API 调用和在项目中应用 REST 所需的一切。

如何构建 URI

一般来说，处理 URI 有两种主要方法：

1. 作为动作
2. 作为资源

考虑以下两个 URI：

1. https://example.com/getUserData?id=1（操作）
2. https://example.com/users/1（资源）

两个示例都显示我们检索 id 为 1 的用户的用户数据。区别在于，在第一个示例中，路由 /getUserData 正在执行操作，而在第二个示例中，路由 /users/1 是资产，它并不表明正在执行什么操作。我们可以说这种类型的 URI 充当名词（因为它是一个事物而不是一个动作，即动词）。

REST 模式要求我们严格使用 URI，如第二个示例。我们希望我们的 URI 是名词，这样我们就可以使用 HTTP 方法作为动词来对这些名词执行操作。例如，我们可以使用 HTTP 方法 GET 检索有关 /users/1 的信息，但我们可以使用 PUT 更新相应用户的信息，或使用 DELETE 完全删除用户。

关于 URI 需要注意的最后一件事是，与上面的示例一样，当引用单个资源（例如本例中的单个用户）时，URI 应以该资源的唯一标识符结尾。引用给定类别中的所有资源时，应省略唯一标识符。

1. https://example.com/users/1 - 引用 id 为 1 的特定用户
2. https://example.com/users - 引用所有用户，无论 id 为何

支持哪些行动

REST 支持 4 个主要操作，我们使用缩写 CRUD 来记住它们：Create、Read、U 更新，D删除。这些操作中的每一个都映射到一个我们可以用来执行该操作的 HTTP 方法。映射如下：

支持的所有操作 URI 组合

每个 REST API 实际上只是（至少）5-6 个路由。在我们的示例中，基本端点将是 /users，我们将假装将其托管在 https://example.com 上。

• 获取 https://example.com/users
  • Action：返回所有用户资产（每个资产为一个用户）
  • 请求正文：空
  • 响应正文：用户资产列表（作为 JSON 数组）
• GET https://example.com/users/[id] （[id] 是一个变量）
  • 操作：仅返回单个请求的用户资产
  • 请求正文：空
  • 响应正文：仅具有匹配ID的用户资产（作为JSON）
• 发布 https://example.com/users
  • 操作：将一项用户资产添加到集合
  • 请求正文：创建新用户资产所需的所有数据（不需要特定格式，建议使用JSON）
  • 响应正文：插入唯一 ID （作为 JSON） 的新创建的资产
• PUT https://example.com/users/[id] （[id] 是一个变量）
  • 操作：用给定数据完全替换一个现有用户的数据
  • 请求正文：替换现有用户数据所需的所有数据，无论是否已更改（减去 id - 不需要特定格式，推荐 JSON）
  • 响应正文：具有匹配ID 的新更新资产（作为JSON）
• （可选） PATCH https://example.com/users/[id] （[id] 是一个变量）
  • 操作：用给定数据部分替换一个现有用户的数据
  • Request Body：仅需要更新的数据（减去 id - 不需要特定格式，推荐 JSON）
  • 响应正文：具有匹配ID 的新更新资产（作为JSON）
• 删除 https://example.com/users/[id] （[id] 是一个变量）
  • 操作：仅从用户表中删除一条记录
  • 请求正文：无
  • 响应正文：无（仅 HTTP 响应代码）或刚刚删除的具有匹配 ID 的资产中的数据（作为 JSON）

设计考虑因素

除了定义端点是否使用 REST 模式之外，在开始构建端点之前还有很多事情需要考虑。您将来是否有可能想要更新您的端点？您的输出是否应该向用户提供有用的提示？ REST 是否适合您的情况使用？让我们回答其中一些问题。

对您的端点进行版本控制

从一开始就开始考虑 API 的版本控制可能是个好主意，以便将来更容易进行更改。有几种不同的方法可以确定用户选择使用的 API 版本：

• URI 版本控制
  • 版本号被合并到 URL 路径中，通常位于底部
  • 示例：
  • https://example.com/v1/users/1
  • https://example.com/v2/users/1
• 查询参数
  • 版本号作为查询参数附加在 API 端点
  • 示例：
  • https://example.com/users/1?apiVersion=1
  • https://example.com/users/1?apiVersion=2
• 基于标题
  • 版本号是一个特定且唯一的标头字段
  • 示例（请求标头）：
  • x-api-版本：1
  • x-api-版本：2
• 内容协商
  • 版本是根据表征状态或媒体类型确定的。
  • 在下面的示例中，服务器代码会知道firstName是第一个版本的名称，并且在下一个版本中它被更改为givenName。
  • 示例（请求正文）：
  • { 名字: '亨利' }
  • {给定名称：'亨利'}

模拟快速 REST API

有时，尝试一下是了解它们如何工作的最佳工具。我最喜欢的演示 REST 的库之一是 json-server。设置非常简单 - 只需几个步骤。

安装 JSON 服务器

npm install json-server

创建一个简单的数据存储

{
  "users": [
    { "id": "1", "username": "gorwell", "email": "gorwell@gmail.com" },
    { "id": "2", "username": "cdickens", "email": "cdickens@gmail.com" },
    { "id": "3", "username": "jausten", "email": "jausten@gmail.com" },
    { "id": "4", "username": "vwoolf", "email": "vwoolf@gmail.com" },
    { "id": "5", "username": "sking", "email": "sking@gmail.com" }
  ]
}

启动服务器

npx json-server db.json

向本地服务器发出 HTTP 请求

curl -X GET http://localhost:3000/users/1

简单的 CRUD 数据网格

功能齐全的 REST 端点可以使用 ZingGrid 轻松连接到数据网格，只需将基本 REST URI 指向 即可。元素的 src 属性如下

<zing-grid
  src="http://localhost:3000/users"
  editor-controls
></zing-grid>

最后的想法

REST API 在网络上有多种形状和大小，每种都是为了满足特定需求而定制的。通过深思熟虑地构造 URI、选择正确的操作并牢记版本控制，您可以创建一个简单、灵活的 API，开发人员会乐于使用它。通过这些基本步骤，即使是快速原型也可以演变成健壮、可靠、经得起时间考验的 API。

以上是了解 REST API - 不耐烦者指南的详细内容。更多信息请关注PHP中文网其他相关文章！