使用 Node.js 和 Express 编写您的第一个 API：了解 REST API

了解 rest 和 RESTful api

如果您在现代 Web 开发上花费过任何时间，您就会遇到 REST 和 API 等术语。如果您听说过这些术语或使用过 API，但不完全了解它们的工作原理或如何构建自己的 API，那么本系列适合您。

在本教程系列中，我们将从 REST 原则和概念的概述开始。然后我们将继续创建我们自己的完整 API，该 API 在 node.js Express 服务器上运行并连接到 mysql 数据库。完成本系列后，您应该对构建自己的 API 或深入研究现有 API 的文档充满信心。

先决条件

为了充分利用本教程，您应该已经具备一些基本的命令行知识，了解 javascript 的基础知识，并且已经全局安装了Node.js。

什么是 REST 和 RESTful API？

Representational State Transfer 或REST描述了 Web 服务的架构风格。REST 由一组用于在不同系统之间共享数据的标准或约束组成，实现 REST 的系统称为 RESTful。REST 是一个抽象概念，而不是一种语言、框架或软件类型。

REST 的一个松散类比是保留黑胶唱片集合与使用流媒体音乐服务。使用实体黑胶唱片收藏，每张唱片都必须完整复制才能共享和分发副本。然而，使用流媒体服务，可以通过引用某些数据（例如歌曲名称）来永久共享相同的音乐。在这种情况下，流媒体音乐是 RESTful 服务，而黑胶唱片集是非 RESTful 服务。

API是一种应用程序编程接口，它是允许软件程序相互通信的接口。RESTful API只是一个遵循 REST 原则和约束的 API 。在 Web API 中，服务器通过 URL 端点接收请求并发送响应作为返回，该响应通常是 JSON 等格式的数据。

REST 原则

六个指导约束定义了 REST 架构，概述如下。

1. 统一接口：组件的接口必须相同。这意味着使用 URI 标准来识别资源——换句话说，就是可以输入到浏览器位置栏中的路径。

2. 客户端-服务器：存储和操作数据的服务器与请求和显示响应的客户端之间存在关注点分离。

3. 无状态交互：关于每个请求的所有信息都包含在每个单独的请求中，并且不依赖于会话状态。

4. Cacheable：客户端和服务器可以缓存资源。

5. 分层系统：客户端可以连接到终端服务器，或负载均衡器等中间层。

6. 按需代码（可选）：客户端可以下载代码，这会降低外部的可见性。

请求和响应

http您已经熟悉所有网站的 URL 都以（或https安全版本）开头的事实。超文本传输协议或HTTP是 Internet 上客户端和服务器之间的通信方法。

我们在浏览器的 URL 栏中最明显地看到它，但 HTTP 不仅可以用于从服务器请求网站。当您访问 Web 上的 URL 时，您实际上是GET在对该特定资源进行请求，而您看到的网站就是响应的正文。我们将GET很快讨论其他类型的请求。

HTTP 通过打开与服务器端口（ for 、for ）的TCP（传输控制协议）连接来发出请求，***服务器以状态和正文响应。80http443https

请求必须由 URL、方法、标头信息和正文组成。

请求方法

有四种主要的 HTTP 方法，也称为 HTTP 动词，通常用于与 Web API 交互。这些方法定义了将使用任何给定资源执行的操作。

HTTP 请求方法松散地对应于CRUD的范式，它代表Create、Update、Read、Delete。尽管 CRUD 指的是用于数据库操作的函数，但我们可以将这些设计原则应用于 RESTful API 中的 HTTP 动词。

GET是一个安全的只读操作，不会改变服务器的状态。每次您在浏览器中点击一个 URL，例如https://www.google.com，您都在GET向 Google 的服务器发送一个请求。

POST用于创建新资源。一个熟悉的例子POST是在网站或应用程序上注册为用户。提交表单后，POST可能会将包含用户数据的请求发送到服务器，然后服务器会将这些信息写入数据库。

PUT更新现有资源，该资源可用于编辑现有用户的设置。不同于POST,PUT是幂等的，这意味着可以多次进行相同的调用而不会产生不同的结果。例如，如果您POST多次发送相同的请求以在数据库中创建一个新用户，那么它将为您发出的每个请求创建一个具有相同数据的新用户。但是，对同PUT一个用户使用同一个请求会不断产生相同的结果。

DELETE，顾名思义，只会删除现有资源。

响应代码

一旦请求从客户端传递到服务器，服务器将发回 HTTP 响应，其中将包括有关响应的元数据，称为标头以及正文。响应的第一个也是最重要的部分是状态码，它指示请求是否成功、是否有错误或是否必须采取其他措施。

您将熟悉的最著名的响应代码是404，这意味着Not Found。是状态码类的404一部分，表示客户端错误。4xx有五类状态代码，每类都包含一系列响应。

• 1xx： 信息

• 2xx： 成功

• 3xx: 重定向

• 4xx: 客户端错误

• 5xx： 服务器错误

您可能熟悉的其他常见响应是301 Moved Permanently，它用于将网站重定向到新的 URL，以及500 Internal Server Error，当服务器上发生意外的事情导致无法满足预期的请求时，经常会出现错误。

对于 RESTful API 及其对应的 HTTP 动词，所有响应都应在2xx范围内。

200 OK是指示请求成功的响应。GET它在发送或PUT请求时用作响应。POST将返回 a201 Created以指示已创建新资源，并DELETE具有一些可接受的响应，这表示请求已被接受（202），或者由于资源不再存在而没有要返回的内容（204）。

如果您没有收到 2xx 范围内的请求，那可能意味着很多事情。1xx 请求发送额外信息，3xx 请求意味着重定向，4xx 请求意味着客户端错误，5xx 请求意味着服务器错误。

我们可以使用 curl 测试资源请求的状态码，这是一个用于通过 URL 传输数据的命令行工具。使用curl，后跟-ior--include标志，将向 URL 发送GET请求并显示标题和正文。我们可以通过打开命令行程序并使用 Google 测试 cURL 来测试这一点。

curl -i https://www.google.  com

Google 的服务器将响应以下内容。

HTTP/2 200
date: Sun, 21 Aug 2022 19:06:22 GMT
expires: -1
cache-control: private, max-age=0
content-type: text/html; charset=ISO-8859-1
...

如我们所见，curl请求返回多个标头和响应的整个 HTML 正文。由于请求成功通过，响应的第一部分是200状态代码，以及 HTTP 的版本（这将是 HTTP/1.1、HTTP/2 或 HTTP/3）。

由于此特定请求正在返回一个网站，因此返回的content-type（MIME 类型）是text/html. 在 RESTful API 中，您可能会看到application/json响应是 JSON。

有趣的是，我们可以通过输入稍微不同的 URL 看到另一种类型的响应。在curl没有www.

curl -i https://google. com

HTTP/2 301
location: https://www.google.  com/
content-type: text/html; charset=UTF-8

Google 重定向google.com并www.google.  com使用301响应来指示应重定向资源。

REST API 端点

在服务器上创建 API 时，可以通过端点访问其中包含的数据。端点是可以接受和处理GET、POST、PUT或请求的请求的URL DELETE。

API URL 将由根、路径和可选的查询字符串组成。

• Root eg https://api.example.comor https://api.example.com/v2: API 的根，可能由协议、域和版本组成。

• 路径例如/users/或/users/5：特定资源的唯一位置。

• 查询参数（可选）例如?location=chicago&age=29：用于排序，过滤和分页的可选键值对。我们可以将它们放在一起来实现如下示例，它将返回所有用户的列表并使用查询参数limitto过滤响应以仅包含十个结果。

https://api.example.com/users?limit=10

通常，当人们将 API 称为 RESTful API 时，他们指的是用于构建 API URL 端点的命名约定。标准 RESTful API 的一些重要约定如下：

• 路径应该是复数：例如，要获取 id 为 的用户5，我们将使用/users/5，而不是/user/5。

• 端点不应显示文件扩展名：尽管 API 很可能会返回 JSON，但 URL 不应以.json.

• 端点应该使用名词，而不是动词：类似add且delete不应出现在 REST URL 中的词。为了添加新用户，您只需向 发送POST请求/users，而不是类似/users/add. 应开发 API 以处理对同一 URL 的多种类型的请求。

• 路径区分大小写，应使用连字符而不是下划线以小写形式书写。

所有这些约定都是指导方针，因为没有严格的 REST 标准可以遵循。但是，使用这些指南将使您的 API 保持一致、熟悉且易于阅读和理解。

REST 替代方案

REST 是一个很棒的工具，但在某些情况下有一些替代品可能会有所帮助。

1、SOAP

SOAP（简单对象访问协议）是一种创建于 1998 年的 API，在 REST 之前非常流行。有几个主要区别。首先，SOAP 对响应格式的限制要大得多。其次，SOAP 使用 XML 而不是 JSON，这对遗留应用程序很有帮助，但通常比等效的 JSON 更大、更复杂。最后，虽然 SOAP 可以很好地与 HTTP 配合使用，但它还支持 SMTP 等协议。

2、graphql

GraphQL 是 Facebook 创建的一种较新的 API 格式，旨在通过允许客户端准确地告诉服务器它需要什么数据来减少获取数据所需的 HTTP 请求的数量。GraphQL 没有使用 URL 路径，而是使用自定义语法来定义客户端需要的数据，以便客户端在一个请求中准确获取他们想要的内容。

有关 GraphQL 的精彩介绍，请查看 GraphQL上的本课程。

结论

在本文中，我们了解了 REST 和 RESTful API 是什么、HTTP 请求方法和响应代码如何工作、API URL 的结构以及常见的 RESTful API 约定。在下一个教程中，我们将通过使用 Node.js 设置 Express 服务器并构建我们自己的 API 来学习如何运用所有这些理论。