RESTful API使用PUT/PATCH翻转布尔值

Question

什么是在RESTful API中翻转布尔值的适当方法？

例如，考虑一个 `users/toggle_middle_name` 端点。默认情况下，除非用户通过调用端点选择显示他或她的中间名，否则每个用户都不会显示其中间名。

显然，这不是一个 `GET` 请求，因为您将要向数据库写入信息。但是，在 `PATCH/PUT` 请求中，我的一般理解是应该发送参数，表示正在设置的数据是什么。例如，您会发送 `{show_middle_name: true}`。但由于服务器端只是翻转了一个布尔值，理想情况下，在调用之前你无需知道是否需要发送 `true` 或 `false`。只需调用端点，它便从一个值翻转到另一个值，而无需发送任何值。

那么问题就来了，是否可以只是调用 `PUT/PATCH` 端点而不带参数，并在响应中返回结果？或者无参 `PUT/PATCH` API 调用是不被鼓励的？为什么或为什么不？

- DerektheDev

---

仅作为开关的缺点在于服务器无法确认正确结果。如果您丢失一个请求，那么开关可能会执行用户意图的完全相反操作（并且数据库中发生的可能是前端告诉用户正在发生的完全相反操作）。如果在操作完成后发送所需的结果，则结果将不含歧义。 - jonrsharpe

Answer 1

简单来说：不要这样做。

在我看来，没有必要为翻转布尔值创建专门的资源，因为布尔值本身并不能定义一个自包含的实体。

相反，我会将其作为“用户”属性，并使用PATCH在/users/john_doe上进行操作。

{
  "show_middle_name": true/false
}

正如jonrsharpe的评论所指出的那样。

- Johannes Thorn

---

如果服务器上有一个业务规则不允许布尔值的两个值之一被设置，您仍会推荐这种方法吗？例如，有一个payment实体，其中包含一个approved字段：它将从false（创建资源时）开始，然后在某个时间点更新为true，但是一旦批准，它就永远不能再回到false。您会保留PATCH并返回错误（如错误请求），解释该值只能设置为true，还是在这种情况下使用自定义方法，例如POST /payments/{id}/approve？ - julealgon

是的，即使有基础业务规则，我的选择仍然是简单属性而不是翻转端点。但是，您的场景也可以建模为一个 payments/{id}/approval 资源，该资源只能被创建但永远不能被删除。这也允许存储元数据，例如批准日期或批准者。对我来说，这就是建模资源和“方法调用”之间的区别。 - Johannes Thorn

这实际上是对approval资源非常有洞察力的观点。它确实更好地建模了要求。 - julealgon