在 REST API 的 POST 请求中同时使用查询和正文参数是否有意义？

Question

我有一个资源，本质上需要另一个资源作为创建的输入数据。例如：

POST /v1/NewResource
body: {InputResource}

然而，有趣的是，创建 NewResource 的成本很高，而且资源本身是暂时的（不是持久的）。有些消费者可能只需要部分资源。因此，我确实有两个输入参数：创建所需的数据，然后处理来自消费者的指令以控制实际完成的工作量。

我看到两条路（至少）：

POST /v1/NewResource?detailLevel=base|full
body: {InputResource}

与

POST /v1/NewResource
body: {Request.detailLevel and Request.InputResource}

第一个甚至是一个选择吗？有人有任何偏好/经验吗？让有效负载只是所需的数据并与处理指令分开，有一定的优雅性。我意识到这里没有正确或错误的答案，只是对社区的想法感到好奇。

Answer 1

混合 URI 查询和内容看起来像有效的 HTTP，因为规范没有声明它们在接受 POST 请求的 http 服务器应用程序中是互斥的。

RFC 3986将 http 查询字符串定义为 uri 部分，作为定位资源的非分层方式。然而，RESTful 架构通常不会规定 URI 方案以非常具体的方式工作，而是更多地关注满足可缓存性、资源设计和幂等性等属性，而较少关注资源的定位方式。

我宁愿选择第一个路径，因为它detailLevel不完全是资源本身的一部分。