REST API 入门:初学者教程
什么是 API?
应用程序编程接口 (API) 是一组规则和协议,使不同的软件应用程序能够相互通信和交互。API 充当中介,允许开发人员访问和利用另一个软件系统的功能,例如检索数据或执行操作。举个例子吧👇🏽
如果您像我一样喜欢听音乐,您可以使用 Spotify 应用程序来欣赏您最喜欢的歌曲,但您是否知道在幕后,有一个强大的 REST API 可让您请求和检索 Spotify 的原始 JSON 数据?这就像拥有您想要的所有音乐相关信息的后台通行证!
因此,API 使应用程序可以相互通信、共享数据并执行令人惊奇的任务。
什么是 REST API?
REST API(或 RESTful API)基本上是关于客户端和服务器之间的通信,反之亦然,它也是构建遵循 REST 原则的 Web 服务的一种方法。
REST 代表表述性状态转移。它是一种用于设计网络应用程序的架构风格。
这些 API 允许不同的软件系统通过互联网相互通信。
💡 我们将在本文后面看到一些示例。所以如果你还不明白也完全没问题。
REST API 的关键原则
以下是 REST API 的一些关键方面👇🏽
客户端-服务器架构:REST API 遵循客户端-服务器架构,其中客户端向服务器发出请求,服务器响应请求的数据或执行请求的操作。
无状态:REST API 是无状态的,这意味着服务器不会在请求之间存储有关客户端状态的任何信息。来自客户端的每个请求都必须包含服务器理解和处理它所需的所有信息。这会带来可靠的 Web 应用程序。
HTTP 方法:REST API 利用标准 HTTP 方法来执行不同的操作。RESTful API 中最常用的 HTTP 方法是:
- GET:检索资源的表示。
- POST:创建新资源。
- PUT:更新现有资源。
- DELETE:删除资源。
此外,还有其他方法,如 PATCH、HEAD 和 OPTIONS,它们在 REST 架构中具有特定用途。
基于资源:REST API 是围绕资源构建的,资源是 API 公开的实体。可以使用统一资源标识符 (URI) 来标识资源,通常表示为 URL。例如,
/users
可以是用户资源集合的 URI,并且/users/123
可以代表 ID 为 123 的特定用户。当我们看到事物的实际一面时,所有这些事情都会变得很有意义。资源表示:REST API 使用各种媒体类型,例如 JSON(JavaScript 对象表示法)、XML(可扩展标记语言)甚至纯文本,来表示客户端和服务器之间交换的资源。JSON 由于其简单性和易用性而成为最受欢迎的选择。
🔁 REST API 中的请求和响应周期
REST API 中的请求和响应周期仅涉及使用 HTTP 协议在客户端和服务器之间交换信息。客户端向服务器发起请求,指定所需的操作和任何所需的参数。服务器处理请求并生成包含所请求数据或指示操作结果的响应。让我们通过一个例子来更好地理解👇🏽
💡 这个例子将基于我们之前讨论的关键原则。因此,在完成这个示例之前,首先了解它们中的每一个非常重要。
示例
假设我们有一个用于博客平台的 REST API,并且我们想要检索博客文章列表。以下是实现这一目标的步骤
客户 端发送 GET 请求
客户端向服务器的 API 端点发起 GET 请求,该端点负责检索博客文章。请求可能看起来像这样👇🏽GET /api/posts HTTP/1.1 Host: example.com
正如您在上面看到的,客户端通过访问“/api/posts”端点来请求所有博客文章。
“Host”标头指定客户端正在访问的 API 的域或 IP 地址。在本例中,客户端向“ example.com ”域的“/api/posts”端点发出 GET 请求。
服务器 处理请求
服务器接收 GET 请求并识别相应的端点(“/api/posts”)。它了解客户端想要检索博客文章列表。服务器检索数据
服务器访问底层数据库或数据源以获取所需的数据。在本例中,它检索博客文章列表。服务器生成响应
基于检索到的数据,服务器构建包含所请求的博客文章的 HTTP 响应。响应可能如下所示👇🏽HTTP/1.1 200 OK Content-Type: application/json { "posts": [ { "id": 1, "title": "Introduction to REST API", "author": "John Doe", "content": "All you need to know about REST" }, { "id": 2, "title": "Building Scalable APIs with Node.js", "author": "Jane Smith", "content": "Build Scalable APIs" }, ] }
从上面的代码可以看出,服务器返回“200 OK”状态码,表明请求成功。响应正文包含博客文章的 JSON 表示形式,包括标题、作者和其他相关信息。
服务器 发送响应
服务器将生成的响应通过 HTTP 协议发送回客户端。客户 端接收响应
客户端接收来自服务器的响应。然后,它可以提取并处理响应正文中包含的数据。
如果您阅读了之前有关 HTTP 的文章,您将更好地了解响应标头的真正含义。
现在我们已经了解了请求和响应周期的工作原理,现在让我们构建自己的 REST API,它将允许我们使用 HTTP 方法(例如 GET、POST、PUT 和 DELETE)创建、读取、更新和删除数据。
为了实现这一点,我们需要执行以下几个步骤:
定义资源:确定 API 将处理什么类型的数据或实体。例如,如果我们正在为博客构建 REST API,我们的资源可能包括文章、评论和作者。
设计端点:确定代表每个资源的 URL 端点以及将用于对这些资源执行操作的相应 HTTP 方法。例如:
GET /articles
检索文章列表POST /articles
创建一篇新文章PUT /articles/:id
更新现有文章DELETE /articles/:id
删除具有特定 ID 的文章
实现服务器端逻辑:编写服务器端代码来处理这些 API 端点。这涉及处理传入请求、解析请求数据、对数据执行必要的操作(例如,查询数据库)以及构建和发回适当的响应。
测试 API:我们将使用 Postman 等工具来测试 API 端点。向端点发送请求并验证响应是否符合预期。确保测试不同的场景,例如成功的请求、错误情况和边缘情况。
记录您的 API:记录您的 API 非常重要,包括可用的端点、请求/响应格式以及任何其他详细信息或约束。本文档将帮助其他开发人员了解如何与您的 API 交互。
现在让我们直接进入示例 😃
设置项目:
- 在您最喜欢的代码编辑器上为项目创建一个新目录(我们将在本文中使用 vscode)
- 打开终端(CTRL + `)。
- 通过运行以下命令初始化一个新的 Node.js 项目
npm init -y
: - 通过运行以下命令安装 Express.js:
npm install express
。
例如,创建一个新的 JavaScript 文件,
server.js
或任何您喜欢的名称。导入必要的模块并设置 Express.js 服务器👇🏽
const express = require('express'); 常量应用程序 = Express(); 常量端口= 3000;// 您可以选择任何可用的端口 // 解析 JSON 请求的中间件 app.use(express.json()); // 在此定义您的路由和 API 端点 // 启动服务器 app.listen(端口, () => { console.log(`服务器正在 http://localhost:${port}`上运行`); });
定义您的 API 端点
我们将把这部分分成几个部分以便更好地理解👇🏽- 第一段
const express = require('express'); 常量应用程序 = Express(); 常量端口= 3000;// 您可以选择任何可用的端口
- 第一段
此段导入 Express 框架并创建
Express 应用程序的实例。
它还设置服务器将运行的端口号。在
本例中,它设置为 3000,但您可以选择任何可用
端口。
第二段
app.use(express.json());
该行向 Express 应用程序添加了一个中间件。中间件
express.json()
使用 JSON 有效负载解析传入请求
,并使解析后的数据可用req.body
- 第三段
这会初始化一个名为 的数组,让文章 = [ {id: 1, title: '第一篇文章', content: '让痛苦本身成为一种负担。' }, { 编号: 2, 标题:“第二篇文章”, 内容:“对于那些开车和采矿的人来说,这将是丑陋的”, }, ];
articles
该数组将存储文章对象。它包括两篇样本文章作为初始数据。每篇文章都有一个id
、、title
和content
。 - 第四段
这定义了一个 GET 端点,用于app.get('/articles', (req, res) => { res.json(文章); });
/articles
检索文章列表。当向此端点发出 GET 请求时,它会使用articles
JSON 格式的数组进行响应。 - 第五段
app.post('/articles', (req, res) => { const newArticle = req.body; 文章.push(newArticle); res.status(201).json(newArticle); });
- 第三段
/articles
这定义了用于创建新文章的POST 端点。当向此端点发出 POST 请求时,它会从请求正文 ( ) 中提取新的文章对象req.body
。articles
然后使用将新文章添加到数组中articles.push(newArticle)
。它以状态代码 201(已创建)和 JSON 格式的新创建的文章进行响应。
- 第六段
app.put('/articles/:id', (req, res) => { const ArticleId = req.params.id; const updateArticle = req.body; 文章 = 文章.map((文章) => { if (article.id === parseInt(articleId)) { 返回 { ...article, ...updatedArticle }; } 返回文章; }); res.json({ id:articleId, ...updatedArticle }); });
/articles/:id
这定义了用于更新现有文章的PUT 端点。端点 URL 中的部分:id
是文章 ID 的占位符。当向此端点发出 PUT 请求时,它会使用 . 从 URL 中提取文章 ID req.params.id
。它还从请求正文 ( req.body
) 中检索更新的文章对象。然后,代码在数组中搜索具有相应 ID 的文章articles
。如果找到,它会使用展开运算符 ( ) 使用已更新文章的属性来更新文章的属性{ ...article, ...updatedArticle }
。
最后,它以 JSON 格式响应更新后的文章对象。
- 第七段
app.delete('/articles/:id', (req, res) => {
const ArticleId = req.params.id;
const 已删除的文章 = 文章.find(
(文章) => 文章.id === parseInt(文章Id)
);
if (!deletedArticle) {
return res.status(404).json({ error: '文章未找到' });
}
文章 = 文章.filter((文章) => 文章.id !==
parseInt(文章Id));
res.status(204).end();
});
/articles/:id
这定义了用于删除文章的DELETE 端点。端点 URL 中的部分:id
是文章 ID 的占位符。当向此端点发出 DELETE 请求时,它会使用 . 从 URL 中提取文章 ID req.params.id
。然后,代码在数组中搜索具有相应 ID 的文章articles
。如果未找到该文章,则会返回状态代码 404(未找到)和 JSON 格式的错误消息。如果找到该文章,它将articles
使用该filter
方法从数组中删除该文章。
最后,它以状态代码 204(无内容)响应,表示删除成功。
- 八段
app.listen(端口, () => {
console.log(`服务器正在 http://localhost:${port}`上运行`);
});
- 这将启动服务器并侦听指定的
port
. - 服务器启动后,它会记录一条消息,指示服务器正在运行以及可访问的 URL。
这是完整的代码👇🏽
const express = require('express');
常量应用程序 = Express();
常量端口= 3000;// 您可以选择任何可用的端口
// 解析 JSON 请求的中间件
app.use(express.json());
// 使用示例数据初始化文章数组
让文章 = [
{id: 1, title: '第一篇文章', content: '让痛苦本身成为一种负担。' },
{
编号: 2,
标题:“第二篇文章”,
内容:“对于那些开车和采矿的人来说,这将是丑陋的”,
},
];
// GET /articles - 检索文章列表
app.get('/articles', (req, res) => {
res.json(文章);
});
// POST /articles - 创建一篇新文章
app.post('/articles', (req, res) => {
const newArticle = req.body;
文章.push(newArticle);
res.status(201).json(newArticle);
});
// PUT /articles/:id - 更新现有文章
app.put('/articles/:id', (req, res) => {
const ArticleId = req.params.id;
const updateArticle = req.body;
文章 = 文章.map((文章) => {
if (article.id === parseInt(articleId)) {
返回 { ...article, ...updatedArticle };
}
返回文章;
});
res.json({ id:articleId, ...updatedArticle });
});
// DELETE /articles/:id - 删除文章
app.delete('/articles/:id', (req, res) => {
const ArticleId = req.params.id;
const 已删除的文章 = 文章.find(
(文章) => 文章.id === parseInt(文章Id)
);
if (!deletedArticle) {
return res.status(404).json({ error: '文章未找到' });
}
文章 = 文章.filter((文章) => 文章.id !== parseInt(文章Id));
res.status(204).end();
});
// 启动服务器
app.listen(端口, () => {
console.log(`服务器正在 http://localhost:${port}`上运行`);
});
将更改保存在
server.js
文件中。node server.js
通过在终端中运行命令来启动服务器。打开 Postman 或任何其他 API 测试工具。(但我们将在本文中使用 Postman)
使用 Postman 将请求发送到您的 API 端点:
- 对于
GET /articles
,发送 GET 请求至http://localhost:3000/articles
。 - 对于,使用表示新文章的 JSON 负载
POST /articles
发送 POST 请求。http://localhost:3000/articles
- 对于,使用表示更新文章的 JSON 负载
PUT /articles/:id
发送 PUT 请求。http://localhost:3000/articles/{articleId}
- 对于
DELETE /articles/:id
,发送 DELETE 请求至http://localhost:3000/articles/{articleId}
。
- 对于
结论
大家就这样吧!恭喜您阅读完本文🎉🎉。我知道我们所涵盖的所有内容可能看起来令人不知所措,特别是如果您不熟悉 Node.js 或 Express.js。
- 点赞
- 收藏
- 关注作者
评论(0)