rest - RESTfully 公开对资源的操作 - 重载 POST、PUT 和 Controller 资源

Question

假设您有一个 Person 资源，它的一部分表示包括一个 Location 值，该值可以具有诸如“在家”、“在学校”和“在工作”之类的值。您将如何轻松地展示“回家”、“上类”、“上学”等事件？为了便于讨论，让我们规定这些事件需要时间，因此它们是异步执行的，并且有多种方式可能导致它们失败(没有可用的交通工具，旅行中的交通工具故障，其他不可抗力等) .此外，Person 资源还有其他属性和影响这些属性的相关操作(例如，属性=能量级别，操作=饮食/ sleep /锻炼)。

选项 1 :在 Person 资源上重载 POST，提供一个输入参数，指示您希望该人做什么(例如 action=go-to-school)。从 POST 返回 202 并在 Person 的表示中公开 activity-in-progress 状态属性，客户端可以 GET 以观察进度和成功/失败。

好处:保持简单。

缺点:相当于隧道。发生的 Action 隐藏在有效负载中，而不是在 URI、动词、 header 等中可见。此资源上的 POST 动词没有单一的语义含义。

选项 2 :使用 PUT 将 Person 的位置设置为您希望他们拥有的状态。从 PUT 返回 202 并通过 GET 公开正在进行的事件属性以进行状态轮询。

好处:我不确定我看到了什么。

缺点:真的，这只是与另一个动词的隧道。此外，它在某些情况下不起作用( sleep 和进食都会增加能量水平，因此将能量水平设置为更高的值对于您希望资源执行的操作而言是模棱两可的)。

选项 3 :公开一个对 Person 对象进行操作的通用 Controller 资源。例如，创建一个 PersonActivityManager 资源，该资源接受 POST 请求，其参数标识目标 Person 和请求的操作。 POST 可以返回一个 PersonActivity 资源来表示正在进行的事件，客户端可以通过 GET 来监控进度和成功/失败。

好处:通过将事件及其状态与 Person 资源分开，看起来更简洁。

缺点:现在我们已将隧道移至 PersonActivityManager 资源。

选项 4 :
为每个支持的操作建立单独的 Controller 资源，例如一个 ToWorkTransporter 资源，它接受带有标识 Person 的参数(或 URI 元素)的 POST 请求，以及一个 ToHomeTransporter、一个 ToSchoolTransporter、一个 MealServer、一个 Sleeper 和一个 Exerciser。这些中的每一个都从它们的 POST 方法中返回一个适当的任务监控资源(通勤、用餐、 sleep 、锻炼)，客户端可以通过 GET 对其进行监控。

好处:好的，我们终于消除了隧道。每个 POST 只意味着一件事。

缺点:现在讨论了很多资源(也许我们可以将传输器组合成一个接受目标参数的传输器)。其中一些在语义上非常做作(Sleeper？)。它可能更 RESTful，但它实用吗？

Answer 1

好的，我已经研究和思考了大约一个星期。由于没有其他人回答，我将发布我所学的结果。

蒂姆·布雷，在 RESTful Casuistry ，谈论 PUT-ing 状态字段与 POST-ing 到 Controller ， Controller 将执行影响该状态的操作。他使用了一个虚拟机的例子，以及如何以 RESTful 方式暴露“重启按钮”的功能。他说

"If I want to update some fields in an existing resource, I’m inclined to think about PUT. But that doesn’t work because it’s supposed to be idempotent, and rebooting a server sure isn’t. Well, OK, do it with POST I guess; no biggie.

But you’re not really changing a state, you’re requesting a specific set of actions to happen, as a result of which the state may or may not attain the desired value. In fact, when you hit the deploy switch, the state changes to deploying and then after some unpredictable amount of time to deployed. And the reboot operation is the classic case of a box with a big red switch on the side; the problem is how to push the switch.

So, the more I think of it, the more I think that these resources are like buttons, with only one defined operation: push. People have been whining about “write-only resources” but I don’t have a problem with that because it seems accurate. The reboot and halt buttons don’t really have any state, so you shouldn’t expect anything useful from a GET."

Tim 似乎在我的 #3 和 #4 选项之间找到了解决方案，暴露了多个 Controller 资源，但从“过火”中拉了回来，并为所有事情拥有单独的 Controller 资源。

Tim 的帖子引出了 Roy Fielding ( It is OK to use POST) 的另一个帖子，他在其中说，对于存在可监控实体状态的情况以及可能更改该状态的操作，他倾向于使用 POST 而不是 PUT。为了回应评论者的建议，将受监控的状态作为单独的 PUT 资源公开，他说

"we only use PUT when the update action is idempotent and the representation is complete. I think we should define an additional resource whenever we think that resource might be useful to others in isolation, and make use of the GET/PUT methods for that resource, but I don’t think we should define new resources just for the sake of avoiding POST."

最后，Bill de hOra，在 Just use POST讨论了使用 PUT 与 POST 更新集合资源状态的具体案例，以及其中的权衡。