REST API 最佳实践：查询字符串中的参数与请求正文中的参数

Posted 2023-02-16

【中文标题】REST API 最佳实践：查询字符串中的参数与请求正文中的参数

【英文标题】：REST API Best practices: args in query string vs in request body

【发布时间】：2014-10-12 16:19:19

【问题描述】：

一个 REST API 可以在几个地方有参数：

在请求正文中 - 作为 json 正文或其他 MIME 类型的一部分 在query string - 例如/api/resource?p1=v1&p2=v2 作为 URL 路径的一部分 - 例如/api/resource/v1/v2

在上述 1 和 2 之间进行选择的最佳做法和注意事项是什么？ 2 vs 3 覆盖here。

【问题讨论】：

这能回答你的问题吗？ REST API Best practices: Where to put parameters?

除了上述之外，使用header怎么样？

【参考方案1】：

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

何时使用主体：

当参数没有平面键：值结构时 如果值不是人类可读的，例如序列化的二进制数据 当您有大量参数时

何时使用查询字符串：

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

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

【讨论】：

根据开发便利性选择如何构建 API 并不是一个好习惯。

就像@EricStein 说的，你搞错了。

伙计们，我问这个问题的原因是为了得到正确的答案。来吧，写一个答案，我会删除我有缺陷的答案。 @EricStein

@Jonathan api 易于通过人手使用几乎总是好的 api。感谢准确呼唤 KISS

@AkshayHiremath 他指的是您可能会在体内发送其他内容，例如如果您发送 ContentType 标头，例如“image/jpeg”，您需要让您的消息正文包含 jpeg 数据，并且不能在其中包含任何其他内容

【参考方案2】：

在 1 之间进行选择的最佳做法和注意事项是什么？ 和上面的2？

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

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

您可能还想查看wikipedia article about query string，尤其是前两段。

【讨论】：

对上述分析的一个合理结论是，幂等操作最好保存在 url 查询字符串中，而 CRUD 最好保存在严格类型的响应体中，这基本上利用了 SOP 并防止了非常基本的形式社会工程/网络钓鱼攻击

@Rice R 在 CRUD 中是一个幂等操作。

【参考方案3】：

我假设您在谈论 POST/PUT 请求。从语义上讲，请求正文应包含您发布或修补的数据。

查询字符串，作为 URL（URI）的一部分，用于识别您发布或修补的资源。

您要求最佳实践，以下语义是我的。当然，使用您的经验法则应该可以工作，特别是如果您使用的 Web 框架将其抽象为 参数。

你最了解：

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

【参考方案4】：

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

对于 GET 或 DELETE 或任何其他 REST 操作而言，通过 URL 的潜在曝光不是问题。