RESTful API : what to return when updating an entity produces side-effects

Question

我们的其中一个 API 具有 tasks资源。 API 的使用者可以根据需要创建、删除和更新给定的任务。

如果任务完成(即通过 PUT /tasks/<id> 更改其状态)，可能会因此自动创建新任务。

我们正在努力使其保持 RESTful。告诉调用用户已创建新任务的正确方法是什么？我想到了以下解决方案，但我认为它们都有缺点:

在 PUT 上包含一个附加字段包含有关最终新任务的信息的响应。

只返回更新的任务，并期望用户调用 GET /tasks以检查是否已创建任何新任务。

在我看来，选项 1 打破了 RESTful 性，因为该 API 预计仅返回有关更新实体的信息。选项 2 期望用户做某事，但如果他不做，那么没有人会意识到创建了一个新任务。

谢谢你。

更新: PUT调用沿更新任务的完整 JSON 表示形式返回 HTTP 200 代码。

@tophallen 建议拥有一个任务树，以便(如果我做对了)选项 2 中返回的实体包含新任务作为直接子任务。

Answer 1

你真的有 2 个选项有 200 个状态 PUT，你可以做标题(如果你这样做，请查看 this 帖子)。当然不是一个糟糕的选择，但你会想确保它在整个站点范围内标准化，有据可查，并且你没有任何东西，比如防火墙/F5/etc/重写你的标题。

不过，这样的事情将是一个公平的选择:

HTTP/1.1 200 OK
Related-Tasks: /tasks/11;/tasks/12

{ ...task response... }

或者您必须在响应正文中向客户端提供一些指示。您可以拥有一个支持子任务的任务结构，或者您可以标准化所有响应以包括“元”内容的空间，即

HTTP/1.1 200 OK
{
    "data": { ...the task },
    "related_tasks": [],
    "aggregate_status": "PartiallyComplete"
}

像这样在任何地方使用的东西(有点工作，因为听起来你不仅仅是开始这个​​项目)可能非常有用，因为你也可以将它用于分页等场景。

就个人而言，我认为如果您制作了 related_tasks属性只包含调用子任务的路由，或调用 id 的路径，这可能是最好的、更轻的响应，因为客户端可能并不总是关心立即调用以检查所述子任务。

编辑:
实际上，我考虑得越多-在您的情况下， header 越多-因为客户端可以在任务处理期间的任何时候更新任务，可能有也可能没有子任务在进行中-因此修改数据当子任务开始时客户端调用更新任务的机会的结构似乎比好处更多。标题将允许您轻松添加子任务并在任何时候通知用户 - 您可以将相同的内容应用于恰好立即完成并启动子任务等的任务的 POST。它可以轻松支持更多比一项任务。我认为这也让它保持最安静并减少服务器调用，客户端总是能够知道进程链中发生了什么。 header 的细节可以定义，但我相信在这样的场景中更传统的是让它指向资源，而不是资源中的键。

如果还有其他选择，我很想听听他们的意见。