如何在 REST API 搜索查询中返回过滤元数据答案

【问题标题】：How do I return filtering meta data in a REST API search query如何在 REST API 搜索查询中返回过滤元数据
【发布时间】：2014-03-19 22:42:12
【问题描述】：

我目前正在用 PHP 设计和实现一个 RESTful API。该 API 允许用户搜索酒店。

搜索请求的简化示例是：

GET hotels/searchresults?location=<location>     #collection of hotels within location

响应还包含有关返回集合的一些元信息。响应的基本结构是：

“meta": {
     “totalNrOfHotels": 100,
     "totalNrAvailable": 80
},
“hotels": [
     {
     “id": 123,
     “name": "Hotel A"
     },
     {
     “id": 135,
     “name": "Hotel B"
     },

     ...
]

这个资源也支持分页：

GET hotels/searchresults?location=<location>&offset=0&limit=20

现在，有一些过滤器可以应用于搜索结果，例如星级，评分。例如，如果我只想要 2 星酒店，我可以查询：

GET hotels/searchresults?location=<location>&offset=0&limit=20&stars=2

现在，在用于过滤的用户界面中，通常会显示每个过滤器设置可用的选项数量：

在我看来，这些数字可以看作是关于搜索查询的元数据。因此，我们可以在响应的元数据中添加一个额外的字段：

“meta": {
     “totalNrOfHotels": 100,
     "totalNrAvailable": 80
     “filterNrs": {
          "stars”: {
               “1": 1,
               “2”: 9,
               “3”: 39,
               “4”: 12,
               “5”: 11,
               “none”: 9
          }
     }
},
“hotels": [
     {“id": 123,
     “name": "Hotel A"
     },
     {“id": 135,
     “name": "Hotel B"
     },

     ...
]

所以，我有两个问题：

这个“filterNrs”属性是否应该像上面建议的那样位于元部分？对我来说，作为单独的资源/请求没有意义
我们如何处理这会减慢查询速度的事实？我更愿意将“filterNrs”字段设为可选。我们正在考虑使用“metaFields”参数来允许用户指定她想接收元数据中的哪些字段。我们已经通过“fields”参数支持返回的酒店。（类似于：https://developers.google.com/youtube/2.0/developers_guide_protocol_partial ). 或者，我们将这个字段 filterNrs（或完整的元信息）放在一个单独的资源中，例如 hotels/searchresults/meta。从开发人员的角度来看，您希望将其拆分为多个资源还是拥有一个可以选择的资源显示全部或部分元信息？

【问题讨论】：

标签： api rest

【解决方案1】：

每颗星的评分是否有所不同？例如，对于以下查询，我是否会得到不同的“filterNrs”？

GET hotels/searchresults?location=1
GET hotels/searchresults?location=2

我希望这样的过滤器是上下文相关的，因此不同的位置会根据星数返回不同的数字，这表明这是与查询相关的某种形式的上下文信息。

否则，如果结果是全局的，则表明它是一个单独的资源。如果它是一个单独的资源场景，您可以使用链接来访问它的数字和其他详细信息：

“meta": {
     “totalNrOfHotels": 100,
     "totalNrAvailable": 80
     “filterNrs": {
          "stars”: {
               "options" : ["1", "2", "3", "4", "5", "none"],
               "details" : "http://example.com/stars"
          }
     }
},

【讨论】：