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

Question

我正在尝试设计用于启动、停止、....（和其他操作）某些域中的某些机器的 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要更新，第二个可能有问题？

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