RESTful API设计：URL参数默认值设置合理性及责任归属探讨

首先直接给出结论：在RESTful API中为省略的参数设置默认值是完全可行且合理的，这也是行业内的普遍做法，但确实存在引发混淆的可能性——不过只要做好文档和约定，这种风险完全可以规避。

为什么设置默认值是合理的？ #

• 提升API易用性：客户端不需要每次都传递所有可选参数，比如分页场景下的limit、page，如果用户只关心分类下的内容，不用每次都写limit=100，降低了调用成本。
• 服务端可控性：通过默认值可以避免客户端误传过大的limit导致服务端负载过高，比如你例子里默认limit=100，既满足大部分场景的需求，也防止一次性拉取海量数据拖垮服务器。
• 符合REST设计原则：REST强调简洁性，合理的默认值能让API接口更简洁，减少冗余请求参数。

会不会造成开发者困惑？ #

取决于你是否把默认值的规则讲清楚：

• 如果你的API文档里明确标注了每个可选参数的默认值（比如在limit参数说明里写默认值：100，最大值：500），开发者完全不会困惑，反而会觉得API设计很贴心。
• 真正容易引发困惑的场景是：默认值不符合直觉，且文档没有说明。比如默认排序是按修改时间倒序，但开发者直觉是按创建时间正序，这时候就会出现预期外的结果。

你举的例子/posts?categories=20,21,18默认limit=100，传limit=200就覆盖，这种是非常清晰的规则，只要文档写清楚，绝对不会有问题。

参数默认值的责任归属？ #

核心责任在服务端，但要兼顾客户端的灵活性：

• 服务端主导：因为服务端需要控制资源消耗、接口性能，比如默认limit的大小是服务端根据自身承载能力决定的，不能让客户端随意设置过大的值。
• 允许客户端覆盖：提供参数让客户端可以根据自己的需求调整（比如需要批量导出数据时传limit=200），平衡服务端稳定性和客户端需求。
• 特殊情况：如果某些参数的默认值需要适配不同客户端场景，可以考虑通过请求头或者版本号来区分，但这种情况比较少见，大部分场景下统一的服务端默认值就足够了。

一些最佳实践 #

• 选择符合直觉的默认值：比如分页默认page=1、limit=20，排序默认按创建时间倒序，符合大多数开发者的使用习惯。
• 文档优先：在API文档的每个参数说明里明确标注默认值、取值范围，甚至可以在示例请求里体现默认值的效果。
• 设置参数上限：比如即使客户端传limit=1000，服务端也只返回500条数据，并在响应头或者返回体里说明实际返回的数量，避免服务端过载。
• 避免随意修改默认值：如果必须修改（比如把默认limit从100改成200），最好通过API版本升级来处理，或者提前通知开发者，防止老客户端出现预期外的行为。

内容的提问来源于stack exchange，提问作者AndrewMcLagan