如何使用附加保存功能以及搜索功能 HTTP API 调用

Question

我已经实现了一个 /GET HTTP 端点来提供搜索功能。用户在查询参数中发送搜索词并接收包含所有搜索结果的 JSON 响应。

现在我必须添加一个新功能，即保存搜索。这意味着用户发送相同的搜索参数，也可以发送一个布尔参数，比如 save=true。在这种情况下，我必须将搜索词保存在数据库中以备将来使用。但是这个参数不是必须的。

我对以下几点感到困惑：

1. 修改相同的 GET HTTP 端点，允许在查询参数中添加额外的 save 参数。
2. 修改相同的 GET HTTP 端点，但在请求正文中传递保存参数而不是查询参数作为其后端状态更改参数。
3. 使用单独的端点使用 POST 方法保存参数。

这样做的标准/可接受的方式是什么？

Answer 1

据我了解您的问题，您尝试存储搜索请求并通过存储它还一次性检索响应？

通常GET 用于检索资源的状态，但由于此方法定义为safe，如果为调用的资源创建了某些状态，则不应使用它，因为它会保留搜索查询。 RFC 7231 进一步声明：

GET 请求消息中的有效负载没有定义的语义；在 GET 请求上发送有效负载正文可能会导致某些现有实现拒绝该请求。

因此，我会避免使用选项 #1 或 #2，因为这可能会破坏某些客户端的互操作性。

另一方面，POST 在RFC 7231 中定义为

POST方法请求目标资源根据资源自身的特定语义处理请求中包含的表示。

因此，它应该在其他 HTTP 操作不适合的所有情况下使用。 HTTP 规范进一步定义了创建新资源时应返回 201 Created HTTP 状态代码，包括名为 Location 的 HTTP 响应标头，其中包含已创建资源的 URI。此 URI 稍后可用于检索其状态（即执行的搜索结果）。

从客户端的角度来看，您基本上是在服务器上存储一些查询定义，而不关心服务器实际将其保存在何处或如何保存。您所关心的只是检索您以后可以调用的句柄。这不会阻止服务器在响应负载中返回当前搜索结果。而这正是我要做的。

建议步骤：

• 通过 POST 发送搜索请求
• 商店查询定义
• 为存储的查询生成 URI
• 根据查询执行搜索
• 返回带有201 Created 状态代码和指向存储查询的URI 的Location 标头的响应，并将查询结果添加到响应负载中

客户端稍后可以使用返回的 URI 来检索资源的当前状态，服务器可以将其解释为：执行为该 URI 存储的查询并返回搜索结果。

REST 架构没有定义 URI 的外观。您可能会根据查询生成 UUID 或生成哈希值。后一种方法的好处是，多个相同的查询不会导致创建额外的查询，而是会重复使用这些查询。在这种情况下，应该执行对现有查询资源的重定向，以告诉客户端他的查询已经存在，这也会向客户端传授查询资源的实际 URI 作为副作用。