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

Question

在设计 HTTP RESTful API 时，是否可以在省略参数时使用具有默认值的参数？ 或者这是否令人困惑？

例如：

/posts?categories=20,21,18

缺少limit参数，因此我们默认将limit=100设置为limit=100

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

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

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

Answer 1

尽管此问题的答案在很大程度上取决于具体情况，但提供合理的默认值还是很常见的。

例如，我们可以看看Google如何通过搜索来处理事情。 搜索猫时，可以使用其q参数： https : //www.google.com/search? q = cats。 Google不会返回所有635,000,000条结果，因为您没有指定限制，它们做出合理的假设，即可以将结果限制为固定数量，并等待您提出更多请求。

进一步研究示例，当使用API​​的客户端忽略限制参数时，您实际上只有两个选择：

1. 返回错误
2. 设置默认值

通常，除非出现实际错误，否则您要避免返回错误（例如，如果端点具有对该过程必不可少的必填字段）。

因此，我们设置了默认值。 在limit参数的情况下，除了响应错误外，无法避免设置默认值。 无论您是否回答每个可能的条目，100个条目，1个条目或不回答，所有这些都是默认类型。 本质上，不选择是一种选择。

Answer 2

当然可以。 只要您的文档得到良好维护，并显示需要哪些paran和具有默认值的paran，它就不会使开发人员感到困惑。 例如，查看GitLab的其余api文档。

Answer 3

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