在不知道其价值的情况下，将 RESTful API 中资源字段的值增加固定数量

Question

我正在从事 API 的工作，负责管理长期运行ning 作业。您可以通过发布到

来创造就业机会

/jobs/

这会为您提供一个带有进度字段的对象

{"progress_percentage": 0.0, "id": 1}

然后您可以通过修补

来更改此作业的实例

/jobs/<job-id>/

虽然作业是运行ning，但我想按 api 来增加进度，因为作业是运行ning，从 0.0 开始，到 100.0 结束。任何给定的作业都可以拆分成更小的任务，这些任务可以运行并发，并且可以分配进度 'chunks'。我希望每个块都增加相对于它的分配进度的进度。例如，如果任务 1 是运行ning 并分配了 30% 的进度块，并且在这个大小为 5 的任务中有一个 for 循环，我希望每次迭代的进度百分比增加 6% for 循环，不管当前进度百分比是多少。

其他工作可能只是想简单地设置百分比（而不是增加它）

那么我的问题是，从 API 设计的角度来看，最理想的方法是什么。

我看到几个选项

1.

PATCH /jobs/<job-id>/

负载为

{"progress_percentage": {"increase": 6.0}}

增加

或

{"progress_percentage": {"set": 35.0}}

设置。

2.

POST /jobs/<job-id>/progress_percentage/

负载为

{"amount" 6.0} or [6.0]

增加或

PATCH /jobs/<job-id>/

负载为

{"progress_percentage" 30.0}

设置。

Answer 1

假设您的 REST API 没有公开，我认为选项 1 更有利。

由于 'progress_percentage' 是 'job' 对象的属性，我认为没有必要引入子资源（即 /progress_percentage)。

此外，如果您想为多个 'job' 属性执行 PATCH，您希望能够将其作为单个请求和有效负载的一部分来执行，而不是触发多个 PATCH 请求.为此，使用 'PATCH /jobs/{job-id}/' 是有道理的。

在不知道其价值的情况下，将 RESTful API 中资源字段的值增加固定数量

Increase the value of a field of a resource in a RESTful API by a fixed amount without knowing it's value

rest

api-design