RESTFULL API 中“操作”的命名约定

Question

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

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

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

/Messages/1/Attachments (Post/Get)

等等但是当涉及到自定义操作（例如以一种方式发送消息）时，我遇到了问题：

/Messages/1/Send (POST)

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

/Message/1/MessageSendRequest (POST)

或者也许这是一个坏主意？在这个例子中它适合，但在某些例子中则不适合。如果 RSt 中存在类似的情况，最佳实践是什么:)

Answer 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。

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

希望这对你有帮助，蒂埃里