RESTFUL API 中“操作”的命名约定
Posted
技术标签:
【中文标题】RESTFUL API 中“操作”的命名约定【英文标题】:naming convention for "Actions" in RESTFULL 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
。
希望对你有帮助, 蒂埃里
【讨论】:
以上是关于RESTFUL API 中“操作”的命名约定的主要内容,如果未能解决你的问题,请参考以下文章
基于属性的路由 VS 基于约定的路由 - ASP.net Core RESTful API 的最佳实践 [关闭]