REST API 为不同的状态命名（这是动词）

Question

我的团队正在构建一个 REST API，其中特定名词有 4 个状态。在我的例子中，它是 Claim。客户端将向 Open / Update/ Close/ Re-Open 声明发送请求。

对于这些请求，我们有不同的 Request/Response JSON 模式

据我所知，已经用谷歌搜索并采纳了建议，add verbs to your API URLs 是一种不好的做法。

场景 1:: 我做了一个 POST href = "/claim"

这里客户端会在POST请求中发送Claim Status Header，我会解析、转换然后验证（基于JSONSchema）JSON 到 POJO 取决于索赔状态。

场景 2:: 我创建 4 multiple service endpoints 考虑这些状态为 Nouns instead of Verbs 因为要求只是那样。

示例：href = "/claim/open" "/claim/update 等

我想去 #2 因为 #1 看起来很乏味和凌乱。

此外，#2我不确定我是否遵守约定。

场景#3同事的另一个想法是我们可以有这样的请求 POST /claim 体内有 4 个状态

{
  'open' : {openJSON},
  'update' : {updateJSON},
  'close' : {closeJSON},
  'reopen' : {reopenJSON},
}

无论状态如何，JSON 的那部分将由客户端发送。

Answer 1

在URI 中不使用动词的做法是基于URI 标识资源的概念。但是，URI 完全有效地标识了对资源执行某些操作的脚本。该资源可以通过 POST 方法执行。

从技术上讲，您可以用这种方式编写整个 API，但最好只在 none 的 HTTP 方法足够时才使用它。这是我的做法。

提出索赔

POST /claims

这会在 /claim/1234 处创建声明资源，其中 1234 是声明编号。

更新声明

PUT /claim/1234 或 PATCH /claim/1234

本质上，客户端从他们的 /claim/1234 副本开始，进行所需的更新并将新状态发送回服务器。

关闭索赔

POST /claim/1234/close

我认为 DELETE 在这种情况下不合适，因为您不希望声明消失，您只是将其标记为已关闭。我希望 /claim/1234 有一个状态字段，指示它是打开还是关闭。从技术上讲，您可以只更新该状态，根本不需要此调用，但对于像这样非常具体的更新，我喜欢有一个专用端点。我认为它能更好地传达意图。

重新提出索赔

POST /claim/1234/reopen

同样，这是一个非常具体的更新，我认为以表达意图的名义值得它自己的资源，但这并不是绝对必要的。另外，如果你想避免使用动词，你总是可以称它为 /claim/1234/reopener。可以说这更有效地表明这是一种可用于重新提出索赔的资源。

REST API Naming For Different States (which are verbs)