REST API url 设计答案

【问题标题】：REST API url designREST API url 设计
【发布时间】：2020-09-18 08:57:26
【问题描述】：

我有一个 REST API，它有一个带有两列表的数据库，product_id 和 server_id，它将 product_ids 提供给请求数据的特定服务器（基于表中的 server_id）。假设我有三台服务器，server_id 分别为 1,2 和 3。

我的设计是这样的：/products/server_id/1 并且通过 GET 请求，我得到了 server_id = 1 的 product_ids json 列表，类似地，/products/server_id/2 将输出 server_id = 2 的 product_ids 列表。

我是否应该删除这些路由并要求发送 POST 请求，其中包含仅在 /products 路由中接收特定 server_id 的 product_id 的说明？

例如，发送有效载荷{"server_id":1} 将产生server_id = 1 的product_ids 列表的响应。

【问题讨论】：

你能和我们分享一些代码吗？
如果POST() 调用 API 的目的是使用每个 server_id 的 product_ids 列表的新记录更新服务器数据库，那么它的作用应该只是更新数据库（尽管您可以消除 GET() 只使用 POST()` 来更新和返回数据）。

标签： python api rest flask python-requests

【解决方案1】：

在 REST API 中，POST 请求只能用于创建新资源，因此为了从服务器检索数据，最佳做法是执行 GET 请求。

如果你想在服务器 9 上加载产品 1、2、4、8，你可以使用这种请求：

GET https://website/servers/9/products/1,2,4,8

在服务器端，如果 products 值包含一个逗号分隔的列表，则返回一个包含所有结果的数组，如果不返回一个只有一项的数组，以保持调用之间的一致性。

如果您需要获取所有产品，您可以只保留以下网址：

GET https://website/servers/9/products

由于 products 参数中没有提供 id，因此服务器应返回所有现有产品作为请求的服务器参数。

注意：如果结果量大，必须分页。

【讨论】：

【解决方案2】：

我是否应该删除这些路由并要求发送 POST 请求，其中包含仅在 /products 路由中接收特定 server_id 的 product_ids 的说明？

通常不会，不会。

GET 向通用组件传达请求消息的语义实际上是只读的（请参阅"safe"）。仅凭这种可供性就可以使许多事情成为可能。例如，蜘蛛可以抓取和索引您的 API，就像它们对网站一样。用户代理可以“预取”资源，等等。

当您决定使用 POST 时，所有这些都会立即消失。

此外，URI 本身有许多有用的用途 - 缓存使用 URI 作为匹配请求的主键。因此，我们可以通过重用已使用特定标识符存储的表示来减少源服务器的负载。我们还可以执行魔术，例如将该 URI 粘贴到电子邮件消息中，而无需任何特定 HTTP 请求的上下文，并且消息的接收者将能够获取该标识符并获取我们想要的资源。

同样，当识别信息在请求负载中，而不是在它所属的标识符元数据中时，我们会丢失所有这些信息。

也就是说，我们有时确实使用有效负载来识别信息，作为一种变通方法：例如，如果我们需要太多的识别信息以至于我们开始看到414 URI Too Long 响应，那么我们可能需要将我们的交互协议更改为在有效负载中使用带有识别信息的 POST 请求（失去了使用 GET 的优势）。

这方面的在线示例可能类似于 HTML 验证器，它接受候选文档并返回所发现问题的表示。这实际上是一个只读操作，但在一般情况下，HTML 文档太长，无法轻松放入 HTTP 请求的目标 uri。

所以我们下注。

在 超媒体 api 中，就像在万维网上使用的那样，我们可以摆脱它，因为要使用的 HTTP 方法是由服务器作为表单元数据的一部分提供的本身。您作为客户端不需要知道服务器的首选语义，您只需要知道如何处理表单数据。

例如，当我在浏览器中输入这个答案时，我不需要知道目标 URI 是什么，或者将使用什么 HTTP 方法，因为浏览器已经知道要做什么（基于HTML 和任何“按需”运行的脚本）。

【讨论】：