用于管理状态的 RESTful API 端点答案

【问题标题】：RESTful API endpoints for managing states用于管理状态的 RESTful API 端点
【发布时间】：2021-12-30 08:48:02
【问题描述】：

我有一个 REST API，想为某些资源实现不同的状态。 API 位于Richardson Maturity Model 的第 2 级。

我已经看到了很多关于改变状态的端点的不同方法，但我不确定推荐的方法是什么。

我的场景如下：我的实体是订单。订单可以打开、关闭和进行中。

我可以使用请求正文向/orders/{id} 发出PATCH 请求

{
 "state": "in-progress"
}

我可以向端点/orders/{id}/status/in-progress 添加一个动作参数并发出POST 请求来触发该动作。但这会有 RPC 的味道。
我可以将状态视为资源并发出PUT 请求来更新它。 /orders/{id}/state

{
  "state": "in-progress"
}

除此之外，我不确定响应正文中应该包含什么。

响应只能是202 Accepted，没有正文。
或200 Ok，更新状态为正文。

{
  "state": "in-progress"
}

或带有订单的200 Ok，它的更新状态为正文。

{
  "id": 1
  "state": "in-progress"
}

或带有订单的200 Ok，它的更新状态+下一个可能的状态作为正文。这感觉像是迈向超媒体/成熟度 3 级的一小步。

{
  "id": 1
  "state": "in-progress"
  "nextStates": ["closed"]
}

有很多机会。似乎我无法对资源等端点进行建模，应该如何为 RESTful API 进行建模。但我也不想使用 RPC 中的操作。而且我知道，如果你有超媒体，那就只能是 REST，但实现起来既复杂又昂贵。

【问题讨论】：

没有通用标准，您分享的所有内容都没有明显错误。超媒体也可以免费使用=)
我的建议是你找到一个设计 RESTful api 的好标准，并尽量坚持下去。

标签： api rest state api-design state-machine

【解决方案1】：

基本思想：资源是文档的抽象。客户端通过请求修改文档将信息发送到服务器。有用的业务活动是对文档的修改触发的副作用。

因此，如果您的客户端想要告诉服务器订单的状态，那么想法是找到具有状态信息的文档，并发送一条消息请求修改该文档。

在网络上，我们通过提交表单来做到这一点 - 描述我们想要对文档进行更改的小消息。可能看起来像

POST /orders/12345
Content-Type: application/x-www-form-urlencoded

action=changeState&state=in-progress

另一种选择是在本地编辑文档，然后向服务器发送编辑后文档的副本

PUT /orders/12345
Content-Type: application/json

{
    "id": "12345",
    "items": [
       "loaf of bread",
       "container of milk",
       "stick of butter"
    ],
    "state": "in-progress"
}

这里的架构与“GET /orders/12345”提供给我们的架构相同，我们将整个文档发送回服务器，包括我们的更改。

当文档非常大（相对于 HTTP 标头）并且更改很小时，我们可能更愿意发送描述更改的补丁文档。例如

PATH /orders/12345
Content-Type: application/json-patch+json

[ {"op":"replace", "path":"/state", "value":"in-progress"} ]

这与 PUT 的想法相同：我们对文档副本进行了更改，并要求服务器更改其文档副本以匹配我们的副本。

除此之外，我不确定响应正文中应该包含什么。

200 OK，任意一个

操作状态的表示（也称为成功消息）
资源的更新表示

元数据（特别是 Content-Location 标头）告诉客户端哪个是哪个。

【讨论】：