放置、发布或修补？答案

【问题标题】：To PUT, POST or PATCH?放置、发布或修补？
【发布时间】：2016-10-10 06:54:36
【问题描述】：

我有一个可用于控制数据库的 REST 服务，我想允许调用停止和启动数据库，但想知道正确的方法是什么？

通过调用停止或启动操作，我正在更改资源的状态，因此 PUT 看起来有点正确，但 PATCH 更好还是 POST 更好？

有什么建议吗？

【问题讨论】：

REST 用于更新和检索资源/数据。我会很惊讶它以这种方式用于控制应用程序，但也许我会学到一些新东西。
这真的取决于视角。 PATCH 可能有意义，因为您正在修改资源；但 POST（开始）和 DELETE（停止）也可能有意义。
@RamblinRose DELETE 可能不是停止数据库的好选择...
Rob - REST 服务不仅仅用于更新资源和检索数据。特斯拉使用他们的 REST 服务允许车主启动引擎、打开后备箱、设置温度等。
如果我的回答对你有用，请告诉我。

标签： rest http-method

【解决方案1】：

替换资源的状态

REST 独立于协议，是resource-oriented 架构。例如，在通过 HTTP 协议实现 REST 应用程序时，资源由 URI 标识，对资源的操作由 HTTP method 表示。

PUT 是用于替换资源状态的 HTTP 方法，资源的新状态将使用例如 JSON 和/或 XML 在请求负载中表示。

因此您可以考虑以下设计来启动/停止数据库：

PUT /databases/:id/status HTTP/1.1
Content-Type: application/json

{
    "value": "started"
}

PUT /databases/:id/status HTTP/1.1
Content-Type: application/json

{
    "value": "stopped"
}

要获取资源的状态，请使用GET：

GET /databases/:id/status HTTP/1.1

响应状态码

您当然需要将手术结果告知您的客户。为此，请使用HTTP response status codes。

一些可能有用的状态：

200：使用此状态表示请求已成功。
202：使用此状态码表示请求已被接受处理，但处理尚未完成。
204：使用此状态码表示服务器已成功完成请求，并且响应负载正文中没有要发送的其他内容。
409：使用此项表示由于与目标资源的当前状态冲突而无法完成请求。

【讨论】：

【解决方案2】：

Jim Webber 解释说“HTTP 是传输文档的应用程序协议”您的应用程序中的状态转换是文档传输触发的副作用。

想想老式的纸质商务办公室：老板过来并在您的收件箱中放了一条 TODO 消息，上面写着“停止数据库”。作为副作用，您可以转动椅子并启动干净的关机程序。

因此，按照惯用方式，您发送到 REST 服务器的表示是 TODO 消息的表示，并且您将其发送到 (a) 代表“收件箱”的资源 - 即 TODO 的特定集合消息——或 (b) 代表 TODO 文档本身的资源。

我有一个可用于控制数据库的 REST 服务，我想允许调用停止和启动数据库，但想知道正确的方法是什么？

通过调用停止或启动操作，我正在更改资源的状态，因此 PUT 看起来有点正确，但 PATCH 更好还是 POST 更好？

由于您要发送完整的消息，而不是尝试对 REST 服务器已经知道的消息进行修改，因此 PATCH 不合适。

DELETE 也不合适 - 删除类似于销毁收件箱中的 TODO 消息。

如果您在客户端用来表示应用程序状态的媒体类型是 HTML，那么您使用的动词应该是 POST，因为HTML doesn't support PUT。

如果您将单个消息的表示传递给表示集合的资源，那么您使用的动词应该是 POST，因为 PUT 的语义意味着“创建/覆盖”一个资源，你表达的语义是追加。

如果您将单个消息的表示传递给仅表示该消息的资源（即：您正在创建消息资源），则 PUT 优于 POST。这里的关键思想是 PUT 承诺服务器上的任何副作用都是幂等的——成功传递 N > 0 个消息副本的副作用等同于仅传递 1 个副本的副作用.使用 PUT 作为动词，不仅与客户端和服务器共享该承诺，还与沿途的所有中间连接器共享。

您的幂等资源也可以支持 POST，并且您可以在 API 中记录收到的消息是幂等处理的，以便客户端能够理解，但没有标准化的方式来通知其他连接器这一事实。

（示例：考虑浏览器中的表单发布。服务器上的资源知道可以以幂等方式处理请求。您可以在 html 本身中记录多次单击按钮是安全的，但您不这样做'没有办法告诉浏览器，所以浏览器会向用户抛出一条消息，说“重新发布可能不安全，你确定是/否？”）

总之，您希望您选择的 HTTP 方法与 统一接口 一致，以便客户端、服务器以及作用于其间消息的所有组件具有共同的理解发生了什么。

【讨论】：