使用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。

• 工具和提示 命令行是你最好的朋友 Patkos Csaba

什么是 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）。

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

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

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

HTTP/2 200 
date: Tue, 14 Aug 2018 05:15:40 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）。

由于此特定请求正在返回一个网站，因此返回的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：用于排序、过滤和分页的可选键值对。
  我们可以将它们放在一起来实现类似下面的示例，它将返回所有用户的列表并使用查询参数limit来过滤响应以仅包含十个结果。

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