启动或关闭某个域中的机器 - PUT /domain/x/machine/y 或 PUT /domain/x/machine？

Posted 2023-02-19

【中文标题】启动或关闭某个域中的机器 - PUT /domain/x/machine/y 或 PUT /domain/x/machine？

【英文标题】：To start or shutdown a machine in some domain - PUT /domain/x/machine/y or PUT /domain/x/machine?

【发布时间】：2021-12-30 17:45:45

【问题描述】：

我正在尝试设计用于启动、停止、....（和其他操作）某些域中的某些机器的 REST API。有两种选择，例如停止，

方法 1：PUT /domains/x/machines 在正文中带有机器名称

PUT http://myserver.com/api/domains/x/machines HTTP/1.1
Content-Type: text/json

 "machine_name": "y", "state": "running" 

方法2：PUT /domains/x/machines/y

PUT http://myserver.com/api/domains/x/machines/y HTTP/1.1
Content-Type: text/json

 "state": "running" 

哪一个更 RESTful？如果机器有属性state要更新，第二个可能有问题？

【参考方案1】：

PUT 表示接近“替换资源的表示”的意思。换句话说，我们应该期望 PUT 请求的主体看起来像 GET 响应的主体。

---

PUT /api/domains/x/machines HTTP/1.1
Host: myserver.com
Content-Type: application/json

 "machine_name": "y", "state": "running" 

这可能不是/api/domains/x/machines 的表示形式。根据资源标识符的拼写，这可能是关于机器集合的信息。

[
 "machine_name": "y", "state": "running" 
]

如果集合中只有一台机器，那可能是正确的；但您应该清楚，如果资源描述了五台机器，并且您正在重新启动其中一台，那么所有五台机器都将在 PUT 请求正文中进行描述。

---

PUT /api/domains/x/machines/y HTTP/1.1
Host: myserver.com
Content-Type: application/json

 "state": "running" 

同样，PUT 请求正文应该看起来像 GET 响应正文，因此如果 state 是表示中包含的唯一属性（在这种情况下，可能可以改进 URI 拼写）。

---

如果此处的目标是仅发送正在更改的信息的表示，则要使用的适当 HTTP 消息是 PATCH

PATCH /api/domains/x/machines/y HTTP/1.1
Host: myserver.com
Content-Type: application/merge-patch+json

 "state": "running" 

---

此外，请记住，在没有大量采用 PUT 或 PATCH 的情况下，Web 取得了灾难性的成功。 It is okay to use POST

POST /api/domains/x/machines/y HTTP/1.1
Host: myserver.com
Content-Type: application/x-www-form-urlencoded

state=running

---

这个具体问题是Tim Bray in 2009提出的，在cmets中有一些非常好的想法。当然，也有一些不太好的想法。为了做好准备，我建议您先花时间查看Webber 2011 - 在尝试将其应用于此特定问题之前，请确保您了解什么是 HTTP。

【讨论】：

谢谢，我可能需要使用 PUT、PATCH 或 POST 来更新、创建资源，而不是对资源执行操作。代码中的逻辑是否应该基于某种约定来决定做什么？我看到有些人在 URL 中添加操作，例如POST /resource/x/start，但是有人说这不是 RESTful。

"在这种情况下，也许URI拼写可以改进"，如何改进URI拼写？这些机器还有很多其他属性。也许 PATCH 更合适。