RESTFUL API 中“操作”的命名约定答案

【问题标题】：naming convention for "Actions" in RESTFULL APIRESTFUL API 中“操作”的命名约定
【发布时间】：2015-12-15 14:09:12
【问题描述】：

我知道 REST 没有严格的规则，但有一些常见的做法可以对其进行标准化。我对这件事有点新鲜。我喜欢处理集合的想法，所以我使用了一种约定，我将资源多元化，例如：

/Messages (POST/GET/)
/Messages/1 (DELETE/PUT)

我也喜欢嵌套集合的想法，例如：

/Messages/1/Attachments (Post/Get)

等等但是在发送消息等自定义操作时我遇到了问题一种方法是：

/Messages/1/Send (POST)

但我也在考虑类似的事情：

/Message/1/MessageSendRequest (POST)

或者这是一个坏主意？在这个例子中它适合，但在某些情况下它不适合。如果 REST 中有这样的东西，最佳实践是什么 :)

【问题讨论】：

【解决方案1】：

事实上，在 URL 中使用“动作”并不是真正的 RESTful。您应该在消息中使用状态字段。

结构类似：

{
  "id": "1",
  "title": "some content",
  "date": "...",
  "status": "draft",
  (...)
}

将状态从draft 更新为sending 将触发电子邮件的发送。您可以注意到有两种方法可以在此地址 /messages/1 上进行此更新：

将方法PUT 与完整的有效负载一起使用。当电子邮件的内容很大时，这可能不太方便。
将方法PATCH 与包含您要更新的内容的有效负载一起使用。这里没有真正的约定。您可以只发送要更新的字段 ({ "status": "sent" }) 或利用 JSON PATCH 格式（参见 http://jsonpatch.com/ 和 https://www.rfc-editor.org/rfc/rfc6902），内容如下：[ { "op": "replace", "path": "/status", "value": "sent" } ]。

如果邮件实际是根据请求发送的，状态将更新为sent。

另一种方法也是可能的。您可以在电子邮件地址 /messages/1 上使用 POST 方法。这将触发电子邮件的发送。不需要任何内容，如果实际发送了电子邮件，则会返回状态代码200 。

希望对你有帮助，蒂埃里

【讨论】：