REST API 基础知识

2025-05-24

REST API 基础知识

🔶 简介

我们生活在一个高度互联的现代世界，每秒都会通过浏览器、服务器、软件和应用程序共享海量数据。为了让所有这些系统相互通信，我们拥有一个关键工具，它是整合所有这些复杂性的关键：API。

在本文中，我分享了我对这项技术的知识、经验和研究，目的是提供对 API、REST 和 HTTP 协议主要基础知识的基本了解。

🔶1 API 概念

API 指的是应用程序编程接口( API)，与其他接口一样，它允许交互。API允许系统之间遵循一组标准和协议进行交互，从而共享功能、信息和数据。换句话说，它为开发人员提供了构建和设计能够与其他产品和服务进行通信的产品和服务的机会。

API概念

我们可以拥有不同架构风格的 API，如今，我们互联网世界的关键部分是 REST，即RE presentational S state Transfer的缩写。

🔶 2 REST 基础知识

REST 是一种开发 Web 服务的架构风格，它使用 HTTP 协议作为通信接口，通过 HTTP 方法传输数据。换句话说，它允许在应用程序内高效地执行基本的数据操作，例如创建、检索、更新和删除信息。

REST API

REST 由 Roy Fielding 于 2000 年在他的博士论文中诞生和创建，据他所说：

“表述性状态转移”这个名称旨在唤起人们对精心设计的 Web 应用程序行为的想象：一个网页网络（虚拟状态机），用户通过选择链接（状态转换）来浏览应用程序，从而将下一页（代表应用程序的下一个状态）传输给用户并呈现给他们使用。

因此，正如 Roy Fielding 所定义的，为了构建一个设计良好的 Web 应用程序，我们可以运用 REST 原则来开发更具可扩展性、可靠性和灵活性的服务。为了实现这一目标，REST 架构有六个约束，并且由这些约束驱动的 API 可以称为 RESTful。

🔸 2.1 客户端-服务器

客户端-服务器 Web 架构的主要原则是关注点分离，这意味着发送请求的客户端与返回响应的服务器完全独立。

客户端-服务器约束

🔸 2.2 无状态

请求中所需的所有信息（状态）都必须由客户端发送。因此，服务器在客户端-服务器通信期间不得存储任何数据，这意味着每个请求都是一个独立的请求。

🔸 2.3 缓存

缓存是一种计算存储结构，专注于保存频繁访问的数据，从而提高性能和网络效率。因此，通过缓存，可以减少甚至消除客户端向服务器发送请求的需要（服务器必须告知该请求是否可以缓存）。

🔸 2.4 接口统一

指客户端和服务器如何通过定义每个请求都必须遵循的接口来共享信息。换句话说，它是客户端和服务器之间的契约，决定了它们之间通信的标准。

这里，我们有四个附加约束，它们是统一接口的一部分：

2.4.1 资源识别

REST 基于资源，资源是可命名的信息。它在请求中用于标识客户端想要访问服务器端的内容。

例如，要检索列表products，必须在 URL 中设置资源：http://api.example.com/products

2.4.2 通过表示来操纵资源

客户端必须确保对服务器的请求具有足够的信息来操作（创建、检索、更新、删除）所通知的资源，该资源可以用多种格式表示，例如 JSON、XML、HTML 等。换句话说，客户端可以在每个对服务器的请求中指定所需的资源表示形式。

例如：客户端可以在请求中指定以 JSON 格式检索资源。

2.4.3 自描述消息

自描述消息通过包含客户端或服务器仅通过检查消息的语义来理解请求和响应所需的所有信息，从而确保通信中的统一接口。

2.4.4 HATEOAS（超文本作为应用状态的引擎）

HATEOAS 意味着服务器发送的响应应该包含客户端在后续请求中可以执行的操作信息。换句话说，服务器指示客户端接下来可以执行的操作。在 REST 标准中，服务器必须仅向客户端发送超媒体（链接）。

🔸 2.5 分层系统

分层系统指的是客户端和服务器之间可以存在更多组件和子系统。换句话说，客户端不能假设自己正在直接与服务器通信，也不知道处理请求和返回响应的复杂性。

例如：客户端向服务器发送请求，但首先要经过代理层进行安全检查。

分层系统约束

🔸 2.6 按需代码

按需代码是唯一可选的约束，这意味着服务器可以向客户端发送可执行代码作为响应。换句话说，例如，当浏览器收到来自服务器的带有 HTML 标签的响应时，就会发生这种情况<script>，因此，当 HTML 文档加载完成后，就可以执行脚本。

🔶 3 请求解剖

基本上，客户端请求有 4 个主要元素，它们构成了与服务器交互所需的所有信息。

🔸 3.1 网址

URL 的全称是“统一资源定位符”（ Uniform Resource Locator），它不仅用于标识资源，还用于指定访问方式。在 API 中，URL 可以称为“基础 URL”（Base URL），这意味着它是每次请求都会使用的基地址。

例如：http://api.example.com

🔸 3.2 URI

URI 是统一资源标识符，用于在 URL 中指定客户端在一次请求中想要访问哪个资源。

例如：http://api.example.com/products

网址：http://api.example.com/
URI：/products

因此，每个 URL 都是一个 URI，但并非所有 URI 都是 URL。

🔸3.3 参数

参数是客户端在请求中发送的信息，用于影响服务器的响应。REST 有 4 种类型的参数，其使用取决于请求所要求的操作类型。

🔸 3.4 主体参数

Body，顾名思义，是请求的主体，包含服务器成功处理请求所需的所有数据。因此，它只用于必须发送信息的请求，例如创建或更新。

JSON 格式的请求主体示例：

{
    “name”: “Laptop”,
    “price”: 1000
    “available”: true
}
Enter fullscreen mode Exit fullscreen mode

🔸 3.5 路由参数

路由参数是插入 URL 中的参数，其中包含用于识别特定资源的信息，以便采取行动，例如：检索、编辑、更新或删除。

例如：http://api.example.com/products/1

在这个给定的例子中，值为 1 的路由参数标识了将在请求中操作的资源。

🔸 3.6 查询参数

查询参数也是插入 URL 中的参数，但主要区别在于它的用例与过滤和搜索资源信息有关，甚至对结果进行分页和排序。

例如：

http://api.example.com/products?name=laptop&available=true

在这个给定的例子中，客户端向服务器传达请求是检索名称等于 laptop 且 available 等于 true 的产品。

🔸 3.7 标题

标头允许在请求中发送额外信息，例如身份验证令牌和内容类型。

例如：

Authorization: Bearer token
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

在这个给定的例子中，客户端发送额外的数据，不仅告知其访问资源的凭证，还告知所需的响应格式。

🔶 4 HTTP 协议

好了，现在我们已经对 REST 基础知识及其约束有了基本的了解，让我们来讨论一下通过定义客户端和服务器之间的交互模式来统治互联网世界的通信标准： HTTP协议（​​超文本传输​​协议）。

HTTP 协议不仅决定了 REST API 中允许的方法（即客户端可以在请求中要求的操作类型），还决定了服务器作为响应返回的状态代码，以便实现良好的通信流程。

HTTP 协议

🔸 4.1 HTTP 方法

客户端可以在请求中使用5种主要方法来操作 API 资源，这些方法与数据库中的 5 种基本数据操作类型相关，例如：创建、检索、更新和删除。

4.1.1 获取

此方法用于通过在 URL 中指定资源来从服务器检索数据。例如，要请求 API 的产品列表，客户端可以发送：

得到http://api.example.com/products

4.1.2 开机自检

此方法用于通过在 URL 中指示并在请求正文中发送资源数据来在服务器中创建新资源。

例如：

邮政http://api.example.com/products

JSON格式的请求主体：

{
    “name”: “Laptop II”,
    “price”: 1000
    “available”: true
}
Enter fullscreen mode Exit fullscreen mode

在这个给定的例子中，将使用提供的信息在数据库中创建一个新产品。

4.1.3 放置

该方法用于通过在URL中识别资源数据来更新服务器中的资源数据，并在请求体中发送将要更新的信息。

放http://api.example.com/products/1

JSON格式的请求主体：

{
    “name”: “Laptop”,
    “price”: 5000,
    “available”: false
}
Enter fullscreen mode Exit fullscreen mode

在这个给定的例子中，ID 为 1 的产品将被更新。

4.1.4 补丁

此方法也用于通过在 URL 中识别来更新服务器中的资源数据，但主要区别在于仅更新特定信息。

修补http://api.example.com/products/1

JSON格式的请求主体：

{
    “available”: true
}
Enter fullscreen mode Exit fullscreen mode

在这个给定的例子中，只有availableID 为 1 的产品的属性将被更新。

4.1.5 删除

此方法用于通过在 URL 中标识来删除服务器中的资源。

例如：

删除http://api.example.com/products/1

在这个给定的例子中，ID 为 1 的产品将被删除。

🔸 4.2 HTTP 状态代码

HTTP 状态码是服务器为了指示客户端请求中的响应类型而返回的代码，仅通过其组和编号即可帮助理解。

最常用的状态代码组和编号是：

4.2.1 第 2 组

指示请求成功的状态组。

代码 200（还行） 201（已创建） 204（无内容）
描述 请求成功 请求成功并创建资源 请求成功，响应主体中没有其他内容

4.2.2 第 3 组

指示重定向响应的状态组，用于通知客户端服务器需要执行重定向到新的 URL。

代码 301（永久移动） 304（未修改） 307（临时重定向）
描述 请求的资源已永久更改，并在响应中提供了新的 URL 请求的资源未被修改，可以使用相同的缓存版本 请求的资源已被临时重定向到另一个 URL

4.2.3 第 4 组

指示客户端出现错误的状态组，这意味着请求构建不正确。

代码 400（错误请求） 401（未授权） 403（禁止访问） 404（未找到）
描述 服务器无法理解请求 客户端未通过身份验证，无法访问资源 客户端无权访问资源 服务器找不到请求的资源

4.2.4 第 5 组

指示服务器端错误的状态组，这意味着客户端正确发送了请求，但在处理时发生了错误。

代码 500（内部服务器错误） 503（服务不可用）
描述 表示服务器遇到意外错误，无法返回请求响应 表示服务器无法处理请求，因为它不可用、过载或正在维护

🔶结论

我希望本文能帮助您对 REST 基础知识有一个基本的理论了解，这是每个开发 Web 服务的程序员必备的知识。

现在您已经掌握了这一核心知识，我邀请您阅读我的另一篇文章，该文章提供了构建 REST API 的令人难以置信的技术的基本概念，只需点击下面的链接即可。

Node.js 的基本概念

由 Cássio Cappellari 用💙 撰写！

文章来源：https://dev.to/cassiocappellari/fundamentals-of-rest-api-2nag
Devto 翻译
PREV
停止滥用.map()！
NEXT
Node.js 的基本概念