Rest API 它是什么 - 逐步举例

你是否想要构建一个【REST API24，但只找到关于“状态转移”和“协议”的抽象理论？ 让我们改变这一点。本文是一篇实用教程。让我们在纸上为 任务管理器（待办事项列表） 设计一个真正的 [REST API]。

读完本指南后，您将准确了解如何构建 URL、使用正确的 HTTP 动词以及设计专业的 JSON 响应。

场景

让我们创建一个 API 来管理 任务。 任务有：455、66 和7（对/错）。

步骤 1：定义资源（名词）

在 REST 中，我们考虑“资源”。这里的主要资源是任务。 URL（端点）必须使用复数名词来表示这些资源。

• ✅ 右：8
• ❌错误：910

URL 标识您正在操作的内容。 HTTP 动词标识操作。

步骤 2：列出并创建（集合）

我们如何与完整的任务列表交互？

列出所有任务

• 请求：11
• 含义：“嘿服务器，给我完整的列表。”
• 响应（200 OK）： 0

创建一个新任务

• 申请：12
• 正文已发送： 1
• 含义：“嘿，服务器，将其添加到集合中。”
• 响应（201 创建）：服务器必须返回创建的对象，现在带有生成的 ID。 2

步骤 3：处理特定项目

现在我们要更改 ID 3 的任务。

阅读特定任务

• 申请：13
• 响应 (200 OK)：仅返回任务 3 中的对象。
• 如果不存在怎么办？：响应404 Not Found。 （使用正确的错误代码非常重要！）。

更新任务（完整版）

• 申请：14
• 正文： 3
• 注意：PUT 通常会替换整个对象。如果您只发送标题，则其余部分可能会被删除（这取决于实现，但这是 PUT 规则）。

部分更新（补丁）

只需将状态更改为已完成，而无需再次发送标题。

• 申请：15
• 身体：16
• 含义：“仅更改此字段”。

删除任务

• 申请：17
• 响应（204 无内容）：成功，但没有任何可显示的内容。

步骤 4：过滤和分页

如果我们有 10,000 个任务怎么办？ 18 会使应用程序崩溃。 我们使用查询参数（19后面的东西）来过滤。这不会更改资源的 URL，只是过滤资源的视图。

• 分页：20
• 过滤器：21（只需给我完整的即可）。
• 搜索：22

HTTP 状态代码（反馈）

RESTful API 必须使用 HTTP 代码来告诉您发生了什么。不要总是在 JSON 中返回 200 和 23 。这会破坏监控工具。

• 200 OK：成功了。
• 201 Created：我成功创建了资源（在 POST 中使用）。
• 204 无内容：它有效，但我没有什么可以向您展示（在 DELETE 中使用）。
• 400 Bad Request：您发送了错误的数据（例如标题丢失）。
• 401未经授权：你是谁？ （缺少令牌）。
• 403禁止：我知道你是谁，但不许你乱搞。
• 404 Not Found：我没有找到。
• 500 Internal Server Error：服务器爆炸（后端开发人员的错误）。

结论

设计 [REST API26 涉及组织和标准化。 通过遵循此模式（URL 中的名词、操作中的 HTTP 动词、正确的状态代码），您可以创建世界上任何开发人员都可以直观理解的 API，而无需阅读 500 页的手册。

现在轮到你了：采用这个模型并将其应用到你的下一个项目中！

另请阅读

• [Rest API 什么 E27
• [REST API：它是什么以及实践步骤28
• [数字平台上的自动化：效率和规模29
• 【数字平台自动化-真实案例最佳实践30
• [数字平台自动化-最佳实践快速指南31
• [后端即服务32