REST API最佳实践:查询字符串与请求正文中的args

Question

REST API可以在几个地方包含参数:

1. 在请求正文中 - 作为json正文或其他MIME类型的一部分
2. 在查询字符串中 - 例如/api/resource?p1=v1&p2=v2
3. 作为URL路径的一部分 - 例如/api/resource/v1/v2

选择上述1和2之间的最佳做法和考虑因素是什么？这里
涉及2对3 .

Answer 1

选择上述1和2之间的最佳做法和考虑因素是什么？

通常,内容主体用于要从服务器上载/下载的数据,并且查询参数用于指定所请求的确切数据.例如,当您上传文件时,在主体中指定名称,mime类型等,但是当您获取文件列表时,可以使用查询参数按文件的某些属性过滤列表.通常,查询参数是查询的属性而不是数据.

当然,这不是一个严格的规则 - 您可以以任何您认为更合适/为您工作的方式实施它.

您可能还想查看有关查询字符串的维基百科文章,尤其是前两段.

Answer 2

我一直使用的推理是，因为POST、PUT、 和PATCH可能具有包含客户可能认为专有的信息的有效负载，所以最佳实践是将这些方法的所有有效负载放在请求正文中，而不是放在 URL 参数中，因为它非常很可能在某个地方，以某种方式，您的 Web 服务器正在记录 URL 文本，并且您不希望客户数据以纯文本形式散布到您的日志文件系统中。

GET对于或DELETE或任何其他 REST 操作来说，通过 URL 进行的潜在暴露并不是问题。

Answer 3

我假设你在谈论POST/PUT请求.在语义上,请求正文应包含您要发布或修补的数据.

查询字符串作为URL(URI)的一部分,用于标识要发布或修补的资源.

你问过最佳实践,语义是我的.当然,使用您的经验法则应该有效,特别是如果您使用的Web框架将其抽象为参数.

你最了解的:

• 某些Web服务器对URI的长度有限制.
• 您可以使用CURL在请求正文中发送参数.
• 您发送数据的位置不应对调试有影响.

Answer 4

以下是我的经验法则......

什么时候使用身体:

• 当参数没有平键时:值结构
• 如果值不是人类可读的,例如序列化二进制数据
• 当你有很多参数时

何时使用查询字符串:

• 当参数这样你想在调试时看到它们
• 如果您希望能够在开发代码时手动调用它们,例如使用 curl
• 当参数在许多Web服务中很常见时
• 当您已经发送不同的内容类型时,例如 application/octet-stream

请注意,您可以混合使用 - 将常用的,可调试的那些放在查询字符串中,然后将所有其余内容放入json中.