REST API 最佳实践 – REST 端点设计示例

在 Web 开发中，REST API 在确保客户端和服务器之间的顺畅通信方面发挥着重要作用。

您可以将客户端视为前端，将服务器视为后端。

客户端（前端）和服务器（后端）之间的通信通常不是超级直接的。因此，我们使用一个称为应用程序编程接口（或API）的接口来充当客户端和服务器之间的中介。

由于 API 在这种客户端-服务器通信中起着至关重要的作用，因此在设计 API 时应始终牢记最佳实践。这有助于维护它们的开发人员以及使用它们的开发人员在执行这些职责时不会遇到问题。

在本文中，我将带您了解在制作 REST API 时要遵循的 9 个最佳实践。这将帮助您制作出最好的 API，也让 API 使用者的生活更轻松。

首先，什么是 REST API？

REST 代表 具象状态转移。它是Roy Fielding在2000年创建的一种软件架构风格，用于指导Web架构的设计。

任何遵循REST设计原则的API（应用程序编程接口）都被称为RESTful。

简而言之，REST API是两台计算机通过HTTP（超文本传输协议）进行通信的媒介，其通信方式与客户端和服务器通信的方式相同。

REST API 设计最佳实践

1. 使用 JSON 作为发送和接收数据的格式

过去，接受和响应 API 请求主要是用 XML 甚至 HTML 完成的。但如今，JSON（JavaScript Object Notation）在很大程度上已成为发送和接收API数据的事实格式。

这是因为，例如，对于XML，解码和编码数据通常有点麻烦 - 因此XML不再受到框架的广泛支持。

例如，JavaScript有一个内置的方法，通过fetch API解析JSON数据，因为JSON主要是为它制作的。但是，如果您使用的是任何其他编程语言，例如Python或PHP，它们现在都有方法来解析和操作JSON数据。

例如，Python 提供并用于处理 JSON 数据。 json.loads() json.dumps()

若要确保客户端正确解释 JSON 数据，应在发出请求时将响应标头中的类型设置为。 Content-Type application/json

另一方面，对于服务器端框架，其中许多会自动设置。例如，Express现在拥有用于此目的的中间件。NPM 包仍然适用于相同的目的。 Content-Type express.json() body-parser

2. 在端点中使用名词而不是动词

设计 REST API 时，不应在终结点路径中使用谓词。终结点应使用名词，表示每个终结点的作用。

这是因为 HTTP 方法（如 、 、 、 和）已经是用于执行基本 CRUD（创建、读取、更新、删除）操作的谓词形式。 GET POST PUT PATCH DELETE

GET 、 、 和 是最常见的 HTTP 谓词。还有其他的，如、、、等。 POST PUT PATCH DELETE COPY PURGE LINK UNLINK

因此，例如，终结点不应如下所示：

https://mysite.com/getPosts or https://mysite.com/createPost

相反，它应该是这样的： https://mysite.com/posts

简而言之，您应该让 HTTP 谓词处理终结点的作用。因此，将检索数据，将创建数据，将更新数据，并将摆脱数据。 GET POST PUT DELETE

3. 使用复数名词命名集合

您可以将 API 的数据视为来自使用者的不同资源的集合。

如果你有一个类似 的终结点，则可以删除包含请求的帖子，或者使用 或 请求更新帖子，但它不会告诉用户集合中可能存在其他一些帖子。这就是为什么你的集合应该使用复数名词。 https://mysite.com/post/123 DELETE PUT PATCH

因此，它应该是 ， 而不是 。 https://mysite.com/post/123 https://mysite.com/posts/123

4. 在错误处理中使用状态代码

在响应对 API 发出的请求时，应始终使用常规 HTTP 状态代码。这将有助于您的用户了解正在发生的事情 - 请求是否成功，或者是否失败，或者其他原因。

下表显示了不同的 HTTP 状态代码范围及其含义：

状态代码范围	意义
100 – 199	信息性响应。
例如，102 表示正在处理资源
300 – 399	重定向
例如，301 表示永久移动
400 – 499	客户端错误
400 表示请求错误，404 表示找不到资源
500 – 599	服务器端错误
例如，500 表示内部服务器错误

5. 使用嵌套在端点上显示关系

通常，不同的端点可以相互链接，因此您应该嵌套它们，以便更容易理解它们。

例如，在多用户博客平台的情况下，不同的帖子可以由不同的作者编写，因此在这种情况下，诸如这样的端点将进行有效的嵌套。 https://mysite.com/posts/author

同样，帖子可能有其单独的评论，因此要检索评论，像这样的端点将是有意义的。 https://mysite.com/posts/postId/comments

您应该避免深度超过 3 层的嵌套，因为这会使 API 变得不那么优雅和可读。

6. 使用筛选、排序和分页来检索请求的数据

有时，API的数据库可能会变得非常大。如果发生这种情况，从此类数据库中检索数据可能会非常慢。

筛选、排序和分页都是可以对 REST API 集合执行的操作。这允许它只检索，排序和排列必要的数据到页面中，以便服务器不会被请求占用太多。

以下为筛选终结点的示例：

此终结点将获取任何具有 JavaScript 标记的帖子。 https://mysite.com/posts?tags=javascript

7. 使用 SSL 确保安全

SSL 代表安全套接字层。这对于 REST API 设计中的安全性至关重要。这将保护您的API，并使其不易受到恶意攻击。

您应该考虑的其他安全措施包括：使服务器和客户端之间的通信私密化，并确保使用API的任何人都不会获得超过他们请求的内容。

SSL证书不难加载到服务器上，并且主要在第一年免费提供。在无法免费购买的情况下，购买它们并不昂贵。

通过 SSL 运行的 REST API 的 URL 与不通过 SSL 运行的 REST API 的 URL 之间的明显区别是 HTTP：
中的“s”在 SSL 上运行。
不在 SSL 上运行。 https://mysite.com/posts http://mysite.com/posts

8. 通过版本控制保持清晰

REST API 应具有不同的版本，因此不会强制客户端（用户）迁移到新版本。如果您不小心，这甚至可能会破坏应用程序。

Web开发中最常见的版本控制系统之一是语义版本控制。

语义版本控制的一个示例是 1.0.0、2.1.2 和 3.3.4。第一个数字表示主要版本，第二个数字表示次要版本，第三个数字表示修补程序版本。

来自科技巨头和个人的许多RESTful API通常都是这样的：
对于版本1
，版本2 https://mysite.com/v1/ https://mysite.com/v2

Facebook以这种方式发布他们的API：

Spotify以相同的方式进行版本控制：

并非每个 API 都是如此。Mailchimp以不同的方式版本自己的API：

以这种方式使 REST API 可用时，不会强制客户端迁移到新版本，以防它们选择不这样做。

9. 提供准确的 API 文档

当您制作REST API时，您需要帮助客户端（消费者）学习并弄清楚如何正确使用它。最好的方法是为 API 提供良好的文档。

文档应包含：

• API 的相关端点

• 终结点的示例请求

• 以多种编程语言实现

• 针对不同错误及其状态代码列出的消息

可用于 API 文档的最常用工具之一是 Swagger。您还可以使用 Postman（软件开发中最常见的 API 测试工具之一）来记录 API。

结论

在本文中，您了解了构建 REST API 时要记住的几个最佳实践。

请务必将这些最佳实践和约定付诸实践，以便您可以构建功能强大的应用程序，这些应用程序运行良好、安全，并最终使 API 使用者的生活更轻松。

感谢您的阅读。现在，使用这些最佳实践制作一些 API。