长期运行的创建过程的推荐工作流程

Question

我正在设计一个RESTful API，涉及客户提交创建资源的请求，让我们说一个报告。由于有正当理由不值得进入，此过程可能需要至少30秒，最多几分钟才能成功完成。我正在尝试确保此API易于使用且直观易用，因此我只想获得一些关于我正在考虑的事情的反馈。

1. 客户POSTs向/reports请求机构
2. 服务器使用202 Accepted和Location: /jobs/{jobId}标头进行响应
3. 客户GETs /jobs/{jobId}并接收200 OK和响应体如{"status": "pending"}（缩写）
4. 客户端重试，直到他们获得200 OK（未更改）和类似的身体

   {
   "status": "complete",
   "location": "/reports/{reportId}",
   details": { ... }}
   }

5. 客户GETs /reports/{reportId}检索他们的报告

我认为有些事情与上述不同：

1. 有/jobs/{jobId}资源返回303 See Other与Location: /reports/{reportId}标头准备好了。我看到的一些博客帖子和SO答案采用了这种方法。我决定反对它，因为我们希望将这些工作保留为一流的资源，例如：我们希望能够查看过去24小时内提交的所有工作，过去15分钟内所有失败的工作，等等。此外，似乎303 See Other真的不应该返回一个机构，因为客户应该被重定向到Location网址，所以他们无论如何都不会看到它。
2. 有客户POST到/jobs而不是/reports。我觉得这两种选择都是可辩护的，但对于客户来说，如果他们想要创造一个report他们应该POST到/reports似乎不那么令人惊讶。话虽这么说，得到一个回应指向他们job而不是report可能会令人惊讶。
3. 无论客户POST到/reports还是/jobs，因为我立刻创建了job，也许我应该返回201 Created而不是202 Accepted。

无论如何，这就是我目前对此的想法。任何确认，建议，尊重解释分歧等都非常感谢。

谢谢。

Answer 1

我们希望将这些工作保留为一流的资源，例如：我们希望能够查看过去24小时内提交的所有工作，过去15分钟内所有失败的工作，等等。

如果工作和报告都是一流的，那么我建议给每个人提供通常明显的，无聊的语义：

• POST /jobs返回201 Created和Location: /jobs/{id}头球。毕竟，工作立即创建（报告是N / A）。 或者你可以让它返回一个ETag标题（见下）。
• GET /jobs/{id}返回200 OK;响应主体指示报告的准备情况和（如果准备好）/reports/{id}的URI。 您可以选择通过返回If-None-Match来处理304 Not Modified，直到准备就绪发生变化。当然还有一个ETag标题。
• 当然GET /reports/{id}的作品。

---

附：如果我没有弄错的话，Location标题应该是完整的URI，例如https://example.com/path/to/thing不仅仅是相对路径/path/to/thing。如果你这样做，可能同样对任何JSON响应location值？这样，客户端可以在发出请求时按原样使用这些值 - 这对他们来说更方便，如果他们不对协议/主机进行硬编码，则会更好。