通过向另一个（相关）资源发送 POST 请求来创建/修改资源

Question

我正在为测试和测试运行元数据设计一个 RESTful API。我有两个资源：Test 和 TestRun。在后台，它们在数据库中具有一对一的关系。

首先我通过将POST 发送到api/v1/test 来创建Test 资源。

那么我必须开始这个测试。我通过向api/v1/test/{id}/run 发送POST 来做到这一点，这会创建一个与Test 资源相关的TestRun 资源。

然后我也可以通过向api/v1/test/{id}/finish 发送POST 来停止测试，这会修改相应的TestRun 资源（设置一些字段，例如finish_time、result 等）。

API 的用户永远不会拥有GET 访问TestRun 资源的权限，只能通过其相关的Test 资源访问它们。

虽然这种设计对于 API 用户来说看起来非常简单，但我怀疑这对于开发人员来说也同样简单。我想出的这个设计够好吗？它是否违反任何 REST 原则或最佳实践？对此我将不胜感激。

整个 API 的扩展设计说明：https://gist.github.com/Ch00k/27724e29ec1bf044ebbfdabef9e842d5

Answer 1

您的 API 不允许访问测试运行，因此测试运行似乎不是 REST 资源。事实上，就测试而言，您的 URL 是 REST 和 RPC（尤其是 /run 和 /finish 路径）的混合体。

RPC 不是 REST，所以我会稍微修改一下：

• 仅使用 一种 类型的资源，即测试，位于api/v1/test/{id}。
• 测试具有可以使用GET 请求api/v1/test/{id} 检索的状态：
  • status: stopped, started, finished, ...
  • finish_time
  • result
  • ...
• 使用PATCH 请求将测试的状态更改为api/v1/test/{id}，并使用包含新状态的 JSON 正文：{"status": "started"} 来启动测试等。这将替换 RPC 调用。