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

Question

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

1. 客户POST的请求正文/reports
2. 服务器以202 Accepted和Location: /jobs/{jobId}标题
回复
3. 客户GET s /jobs/{jobId}并收到200 OK和回复正文{"status": "pending"}（缩写）
4. 客户重试，直到他们获得200 OK（未更改）且身体为{ "status": "complete", "location": "/reports/{reportId}", details": { ... }} }
5. 客户GET s /reports/{reportId}检索其报告

我做过的一些事情与上面做的不同：

1. 准备好后，/jobs/{jobId}资源返回303 See Other并带有Location: /reports/{reportId}标头。一些博客文章＆amp;我看到的答案采取了这种方法。我决定反对它，因为我们希望将这些工作保留为一流的资源，例如：我们希望能够查看过去24小时内提交的所有工作，过去15分钟内所有失败的工作，等等。似乎303 See Other确实不应该返回正文，因为客户应该被重定向到Location url所以他们无论如何都看不到它。
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;响应正文指示报告的准备情况和（如果准备好）URI到/reports/{id}。

  • 您可以选择通过返回If-None-Match来处理此304 Not Modified句柄，直到准备就绪发生变化。当然还会返回ETag标题。

• 当然GET /reports/{id}有效。

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