REST API url 过滤设计

Question

我一直在环顾四周，大多数人似乎建议使用括号表示法在 REST API URL 中设计过滤范围（例如 /resource?weight[gte]=1&weight[lte]=5 ) 或这个的一些变体......

但是有什么理由我们不能只使用分隔符并在 API 文档中记录预期的顺序？例如/resource?weight=1_5...API 文档会通知客户端模式为 min_max

以上两者是否有任何优点或缺点可以保证一个优于另一个？

Answer 1

以上两者是否有任何优点或缺点可以保证一个优于另一个？

是的。

首先：RFC 3986 中的 URI 生成规则不允许在 URI 的查询部分使用左方括号和右方括号 - 这些字符必须经过 pct 编码。

第二：我们没有将定制查询值分隔符与通用组件通信的好方法。您在这里建议做的类似于对两个值使用单个输入控件 - 并告诉使用表单的人他们应该使用特定模式键入文本。但我们真的没有为此制定标准化的语言。

在标准化URI Templates 方面已经做了很多工作，您的默认选项应该仅限于此处描述的机制。在代码审查中，如果您没有准备好令人信服的支持证据，我会反对您的提议。