api - RESTful 设计：区分取消发布和删除

Question

设计一个 API 并寻求一些建议。

下面是动作：

• publish：发布文档（POST）
• update：更新文档（PUT 或 PATCH）
• unpublish: 把文件拿下来，以后再放（？）
• delete：完全删除文档（DELETE）

有任何想法吗？

谢谢！马特

Answer 1

• 更新和删除非常明显，就像您拥有它们一样。

• 您认为“发布”与“创建”相同吗？“发布”可能意味着获取您创建的文档并使其公开可见。一种思考方式是，您只能创建一次文档，但是您可以多次发布和取消发布它。

您可能会考虑文档的生命周期，以及在“取消发布”之后可以使用它做什么。这有点取决于您想要的序列：“创建（发布？）...取消发布...发布...取消发布...删除”。如果发布/取消发布与创建/删除没有任何不同，那么您可以删除它们并完全避免复杂性。

• 纯粹的 REST 答案是在表示中提供一个属性： { ... "published": true ... } 并让客户端 PUT 更新以更改该状态。如果该状态发生变化，它会触发发布或取消发布文档所需的任何处理。

• 但是，我所在的团队对此感到不舒服，因为公开和技术上可能会对发布文档产生重大影响。因此他们选择将操作视为 POST “数据处理”请求（如 HTTP 规范所提供的），并提供一个 POST URL 来“发布”和“取消发布”文档。

• 还有一些其他的选择。就像将 POST 作为附加动词，并提供一个“已发布列表”URI，允许您将文档添加到已发布列表，执行所需的任何处理：

  POST ht_p://.../documents { 文档 }

  POST ht_p://.../published-documents { id= }

  删除 ht_p://.../published-documents/{id}

  删除 ht_p://.../documents/{id}

编辑：因为 stackoverflow 抱怨而破坏了 pretentend URI。;)