通过复合键获取资源过滤作为查询参数？

Question

我正在考虑创建端点的最佳方法，其中一个过滤器是复合键。

例如，我们有一个休息服务来搜索订单：

/orders/

我们可以按开始日期和最终日期过滤订单：

/orders?dt-start=2017-05-11T17:12Z&dt-final=2017-05-11T17:12Z

直到这里，到目前为止一切顺利。但我想按客户过滤订单。客户由其类型的文档和数字标识。

所以，这样的事情是可能的：

/orders?type=ID&number=123456789

但是类型和数字是仅与一起工作的查询参数，它是一个复合键。但是使用查询参数 - 就像最后一个例子 - 似乎API用户也可以这样做：

/orders?number=123456789
/orders?type=ID

但没有意义。是的，如果只传递了其中一个参数，我可以在响应中返回错误（错误请求），但这对于谁正在读取API端点并不自然。

另一种策略是在同一参数中组合类型和数字，但我从未在任何API中看到过这种情况。

/orders?document=ID-12345678

对我来说也很奇怪。我更喜欢使用分离的参数而不是这个。

那么，有一种方法可以使用查询参数并以更“优雅”的方式解决这个问题吗？

谢谢！

Answer 1

不要组成​​复合键，而是有条件地要求两个参数。这不是很糟糕，IMO比创建一个没有数据（或资源）代表的复合键更清晰。

我之前已经这样做了，所以为了帮助说明我会指出你。 This资源用于查询Cyber​​Facts。查询受日期范围的约束。要获取数据，您可以执行以下两种操作之一。

1. 您可以说?today=true，并获取今天的数据（相当于说?startDate=2017-05-13&endDate=2017-05-13）
2. 您可以使用startDate和endDate查询参数，但是如果您使用其中一个而不是另一个（例如?startDate=2017-05-13），您将收到400 Bad Request状态回复查询和响应正文中的错误消息。

所以在这种情况下，我做了一些事情来完成这项工作

1. 设置更高优先级的参数（today覆盖startDate和endDate）
2. 记录有效行为
3. 提供适当的错误回复

我认为只需要＃2 和＃3 。不知道您的所有用例，我建议使用/orders?type=ID&number=123456789并在number时记录type=ID是一个require查询参数，并且还包含相应的错误（例如：＆＃34;您查询了按类型排序＆＃39; ID＆＃39;但是您没有提供＆＃39;号码＆＃39;查询参数＆＃34;）

Answer 2

如果type参数不存在，如何为type提供默认值（例如'ID'）作为后备（我可能会选择最常用/最常用的文档类型）视你的情况而定）。

对于number参数，我会强制执行它，即通过指定它是 required 参数（文档中的某个位置？）。如果缺席，则返回错误请求。