REST API可以在以下几个地方有参数:

在请求体中——作为json体或其他MIME类型的一部分 在查询字符串中-例如/api/resource?p1 = v1&p2 = v2 作为url路径的一部分-例如/api/resource/v1/v2

在上述1和2之间进行选择的最佳做法和考虑因素是什么? 2 vs 3在这里。


以下是我的经验法则。

何时使用主体:

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

何时使用查询字符串:

当您希望在调试时看到参数时 当你希望能够在开发代码时手动调用它们,例如使用curl 当参数在许多web服务中普遍存在时 当您已经发送了不同的内容类型,如应用程序/八字节流

注意,您可以混合和匹配——将常见的,应该是可调试的放在查询字符串中,并将所有其余的放在json中。


在1之间选择的最佳实践和考虑因素是什么 上面的2呢?

通常,内容体用于将上传/下载到服务器的数据,查询参数用于指定所请求的确切数据。例如,当你上传一个文件时,你在文件体中指定文件名、mime类型等,但当你获取文件列表时,你可以使用查询参数通过文件的某些属性来过滤列表。一般来说,查询参数是查询的属性,而不是数据的属性。

当然,这不是一个严格的规则-你可以用任何你认为更适合你的方式来实现它。

您可能还想查看维基百科关于查询字符串的文章,特别是前两段。


我假设您正在讨论POST/PUT请求。从语义上讲,请求体应该包含您要发布或修补的数据。

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

您要求的最佳实践,以下语义是我的。当然,使用你的经验法则应该是可行的,特别是当你使用的web框架将其抽象为参数时。

你们多半知道:

一些web服务器对URI的长度有限制。 您可以使用CURL在请求体中发送参数。 发送数据的位置不应该对调试有影响。


我一直使用的推理是,因为POST、PUT和PATCH假定有包含客户可能认为专有的信息的有效载荷,最好的实践是将这些方法的所有有效载荷放在请求体中,而不是在URL parms中,因为很可能在某个地方,以某种方式,URL文本被您的web服务器记录下来,而您不希望客户数据以纯文本的形式分散到日志文件系统中。

对于GET、DELETE或任何其他REST操作来说,通过URL暴露的潜在风险都不是问题。