RESTful API 设计：url 参数应该有默认值吗？

Posted 2023-02-19

【中文标题】RESTful API 设计：url 参数应该有默认值吗？

【英文标题】：RESTful API design: Should url parameters have default values?

【发布时间】：2018-09-01 08:20:02

【问题描述】：

在设计 HTTP RESTful API 时，是否可以在省略参数时使用默认值？还是那令人困惑？

例如：

/posts?categories=20,21,18

缺少limit 参数，所以我们默认将限制设置为limit=100

/posts?categories=20,21,18&limit=200

将限制设置为 200，覆盖默认值。

可以在 API 中为参数设置默认值吗？还是这只会让试图理解 API 的开发人员感到困惑？默认参数的责任是否应该由使用 API 的客户端承担？

【参考方案1】：

如果您知道端点的调用者可能会省略 url 中的参数，则可以指定默认值。这样代码就不会被破坏。

【参考方案2】：

虽然这个问题的答案在很大程度上取决于具体情况，但提供合理的默认值是很常见的。

例如，我们可以看看 Google 如何处理他们的搜索。搜索猫时，您可以使用它们的q 参数：https://www.google.com/search?q=cats。 Google 不会返回所有 635,000,000 个结果，因为您没有指定限制，他们会合理地假设他们可以将结果限制在一个设定的数量，并等待您请求更多。

进一步查看您的示例，当使用您的 API 的客户端省略限制参数时，您实际上只有两个选项：

返回错误 设置默认值

通常，您希望避免返回错误，除非确实出现问题（例如，如果端点具有对流程至关重要的必填字段）。

所以我们设置了一个默认值。对于limit 参数，除了响应错误之外，没有办法避免设置默认值。无论您是回复所有可能的条目、100 个条目、1 个条目还是没有条目，所有这些都是默认类型。本质上，不选择就是一种选择。

【参考方案3】：

当然没问题。只要您的文档维护良好并显示需要哪些参数以及哪些参数具有默认值，它就不会让开发人员感到困惑。例如，看看 GitLab 的其余 api 文档。