查询参数或单独的端点以不同的格式返回相同的资源？

Question

所以我有了这个“资源”，因为需要一个更好的词，它是由端点返回的：

GET /my/resource

当前以 JSON 形式返回。这是同步的，端点的调用将获取数据然后返回它。

我正在创建一个新端点，它返回与 CSV 相同的资源。但不是直接作为 CSV，但这将返回客户端可以下载的 GCS 存储桶中文件的链接（我将必须弄清楚如何创建签名 URL，但这与这个问题无关）。

但与其他端点不同，这是异步的。但此端点需要花费一些时间来创建 CSV。所以我的计划是返回 202 Accepted 直到端点实际创建 CSV，然后在 200 OK 中返回指向 CSV 的链接。

所以我的问题是：

1. 这种方式的API设计合理吗？
2. 第二个端点应该是

   /my/resource/csv-link

   还是

   /my/resource?format=csv-link

   ？

关于第二个问题，促使我将其作为查询参数的原因是它本质上是相同的资源，只是以不同的格式返回。但另一方面，我觉得查询参数应该改变返回的数据，而不是数据的形状。就像这些

/my/resource

端点一样，我实际上已经有了一堆可以更改返回行的查询参数。但无论查询参数如何，返回类型都是 Blah 类型的数组，采用 JSON 格式（如果查询参数对其进行过滤，则数组中的行数会减少）。不过，在这种情况下使用相同的端点意味着相同的端点可以返回两种不同的“类型”（即 JSON 或指向 GCS 存储桶的链接），具体取决于输入查询参数。并且混淆了我吐出的 OpenAPI 规范中自动生成的 Typescript 类型的内容。

但同样，对于本质上相同的资源有两个不同的端点也感觉很奇怪。

那么我应该走哪条路，或者我应该做一些完全不同的事情？

Answer 1

1. 对同一资源的不同格式使用

   Accept

   标头。如果您想使用查询参数提供后备，您可以这样做，但通常最好先做正确的事情，然后再添加方便的解决方法。

2. 我认为

   202 Accepted

   不适合这样的

   GET

   请求。我认为使用（例如）POST 请求来启动“创建 CSV 导出”更有意义。如果您喜欢

   GET

   ，您是否考虑过在报告可用之前让 TCP 连接保持打开状态？这样做没有真正的成本，并且由于您的客户端可能是脚本，因此它们可以挂起连接直到准备好，而不是偶尔检查。

另请查看此优秀 RFC 中

wait

标头中的

respond-async

和

Prefer

首选项：

https://www.rfc-editor.org/rfc/rfc7240