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

Question

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

例如：

/posts?categories=20,21,18

缺少limit参数，因此默认情况下我们将限制设置为limit=100

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

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

是否可以在API中使用params的默认值？或者这会简单地混淆尝试理解API的开发人员？默认的params责任应该在使用API​​的客户端吗？

Answer 1

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

例如，我们可以了解Google如何通过搜索完成工作。搜索猫时，您可以使用q参数：https://www.google.com/search?q=cats。 Google不会返回所有635,000,000条结果，因为您没有指定限制，他们会合理地假设他们可以将结果限制为设定的数字，并等待您提出更多请求。

进一步了解您的示例，您实际上只有两个选项可供使用API​​的客户端省略限制参数：

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

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

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

Answer 2

当然没关系。只要您的文档得到良好维护并且显示需要哪些parans以及哪个具有默认值，它就不会混淆开发人员。例如，看一下GitLab的其他api文档。