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

Question

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

POST /v1/NewResource
body: {InputResource}

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

我看到两条路径（至少）：

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

VS

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

第一个甚至可以选择吗？任何人都有任何偏好/经验吗？将有效载荷仅仅作为所需数据并与处理指令分离，有一定的优雅。我意识到这里没有正确或错误的答案，只是好奇社区的想法。

Answer 1

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

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

我宁愿选择第一条路径，因为detailLevel并不是资源本身的一部分。

Answer 2

REST和URI设计实际上没有对错。它实际上归结为个人偏好。 POST有效负载的语义完全取决于服务器。这意味着完全由您决定如何将部分或完整数据彼此区分和/或由服务器处理。

因此，您可以选择几条路线：

• 保持身体有效负载代表身体的全部或部分信息
• 通过URI
发送有关完整或部分数据的信息
• 由于有关内容的信息可能被视为描述主体的元数据，您可以引入一个新的HTTP标头，将内容标记为完整或部分
• 为每种有效内容类型创建自己的内容类型

关于RESTfulness，我选择将此信息作为标题或甚至作为您可以协商的自己的内容类型传递。这样，您既不会使用元信息污染实际有效负载，也不会在URI中公开元数据。

由于引入新的自定义内容类型通常需要一些时间和精力，因此可能需要自定义标头值，这是更简单，更快速的解决方案。