处理RESTful API中的布尔型端点

Question

尽管SO中有关于RESTful API命名约定的多个问题，但我找不到任何关于如何处理布尔类型端点（返回布尔值的端点）的参考资料。

考虑一个API，其中包含资源/products和/orders。订单可能引用多个产品，因此不可能删除与相关订单混淆的产品。在引用了订单的产品上调用DELETE /products/:id将返回409冲突状态码。

到目前为止，一切都很简单明了，但是如果客户端想要确认是否可以删除这个产品怎么办？

一个布尔类型的端点会返回true或false（或以某种方式包含这个值的JSON结构）。GET /products/:id/can-be-deleted。

问题在于can-be-deleted不是(子)资源，它是检查某些东西的动作... 如果RESTful API应该使用名词而不应该在端点中使用动词，那么它也不应该有形容词（deletable、completed）或谓词（can-be-deleted、is-ready）。

如果是这样，那么这方面的惯例是什么？这些信息是否应该有自己的端点？如果是这样，这个端点应该如何命名？如果不是这样，这些信息是否应该成为另一个端点的一部分（例如GET /products/:id返回这些信息）？

- NemoStein

Answer 1

“调用 DELETE /products/:id 删除一个被订单引用的产品会返回 409 冲突状态码。”

“到目前为止，一切都很简单，但是如果客户想要确认这个产品能否被删除怎么办？”

“如果您正在尝试验证一个资源是否可以被删除：”

OPTIONS /products/1

200 OK
Allow: GET, DELETE
Content-Length: 0

请注意，DELETE 的语义属于通过网络传输文件。

相对较少的资源允许使用 DELETE 方法 - 其主要用途是用于远程创作环境，在该环境中用户可以指导其效果。-- RFC-7231

---

在web上，如何知道是否可以提交表单？答案很简单：表单已经提供给你了。如果你没有得到一个表单（或链接），那么就不能使用它。这就是“超媒体作为应用程序状态引擎”的统一接口约束。

我们向表示中添加或删除元素，以指示您可以通过应用程序走哪些路径。作为客户端，您检查表示是否新鲜；如果是，则可以选择发送请求。

---

这里的问题是can-be-deleted不是一个（子）资源，而是一个用于检查某些内容的操作...

并不是这样：它是关于某些内容的报告。

一个“检查某些内容的操作”的经典例子是“健康检查”服务，我们用它来检测主机是否需要从负载均衡器中移除。

任何可命名的信息都可以成为资源——Fielding, 2000 机器并不在乎我们为资源使用什么标识符；因此，如果我们选择，我们可以利用这种自由使事情对人们更容易。通常，对资源模型的清晰理解使得很容易确定候选标识符；因此，当你在发现“好的足够”的标识符时遇到困难时，我建议更多地考虑模型。

- VoiceOfUnreason

Answer 2

建议:

• 聚焦“当前问题”。在这种情况下，是您“删除项目”操作的API(或多个API)。
• 一种选择是有多个API：例如，“查询项目状态”和“删除指定项”。
• 另一种选择是只有一个API(“删除指定项”)，如果无法删除，则报告有意义的状态码/错误消息。
• 没有“一刀切”的答案。这是一个判断。
• 您选择的API名称 - 以及您选择的HTTP动词 - 将成为您决策的一部分。
• 是否将您为“删除”操作偶然发生的选择推广到其他不同操作也是一个判断。

希望对您有所帮助...

PS:

如果您还没有这样做，我鼓励您阅读Roy Fielding的原始论文：

表现层状态转移（REST）

- paulsm4