用于在 Restful API 中对结果进行高级过滤的 URL 设计答案

【问题标题】：URL design for advanced filtering of results in restful API用于在 Restful API 中对结果进行高级过滤的 URL 设计
【发布时间】：2013-08-25 03:17:23
【问题描述】：

让我们举一个资源的通用示例，您可以使用 PHP 中内置的 restful API 进行建模。

一个车库有多辆汽车和多个机械师。
一辆车只有一个车库。
一位机械师拥有多辆汽车和多个车库（他是个工作狂，好吧！）。

所以逻辑说我们的端点应该是

/v1/garages  
/v1/garages/1234
/v1/mechanics
/v1/mechanics/1234
/v1/cars
/v1/cars/1234

如果我们想获得车库 1234 的所有汽车，我们会使用 GET /v1/garages/1234/cars

如果我们想要 34 号车库中的 12 号机械师的所有汽车，我们会使用 GET /v1/mechanics/12/garage/34/cars

但是，如果我们想要 56 号和 78 号车库的所有汽车呢？
我有一些想法，但我能想到的最好的是 GET /v1/cars?garage=[id=[56,78]]

这将允许我们从任何带有黄色油漆和碳纤维发动机罩的车库中通过 GET /v1/cars?garage=[paint=yellow,bonnet=[material=carbon]]&color=green&doors=[2,4]

这似乎是一个合理的想法，还是我会遇到嵌套复杂的问题，这是否足够容易用 PHP 解析？

据我所知，我的另一个想法是 Json，所有 json 在 url 中都是有效的，所以

GET /v1/cars?{"color":"green","doors":[2,4],"garage":{"paint":"yellow","bonnet":{"material":"carbon"}}}

这让开发人员使用起来非常容易，因为现在几乎所有的编程语言都支持 json，而在 API 端我们可以只使用 json_decode($_SERVER[''QUERY_STRING]) 那么使用 Json 有什么问题吗？

第三个想法“创建搜索”

我的意思是我们使用

POST /cars/search 使用上述 Json 作为发布数据，该请求将简单地返回搜索的 ID，然后可以通过 GET /cars/search/{id} 获取结果到该 ID，这将减轻我这边的复杂性并避免请求的 8kb 限制（这是一个 API，不打算被浏览器地址栏使用）。但我担心如果我这样做会违背顶级GET /v1/cars 端点的目的？

【问题讨论】：

stackoverflow.com/questions/207477/…
@DavidBrabant，虽然问题很相似，但它并没有真正完整地回答问题；在发布这个问题之前，我实际上已经阅读了这个问题（以及这里的很多其他问题）。该问题的答案主要只涉及单个实体搜索，而不是跨多个实体进行过滤，这是该问题的主要焦点。

标签： php api http rest search

【解决方案1】：

感谢#laravel irc channel 的乐于助人的人，我与他们进行了长时间的交谈，我们得到了一个似乎有效的答案。

我们选择这个答案是基于以下几点：

易于阅读
查询能力
平坦度（易于解析）
易于过滤

基本要求是

GET /v1/cars?color=green
            &doors=2,4
            &garage[paint]=yellow
            &garage[bonnet][material]=carbon

与以下代码结合使用时

$query = array();
parse_str($_SERVER['QUERY_STRING'], $query);

吐出一个像下面这样的数组，可以在 API 中轻松迭代以进行过滤:)

Array
(
  [color] => green
  [doors] => 2,4
  [garage] => Array
    (
      [paint] => yellow
      [bonnet] => Array
        (
          [material] => carbon
        )
    )
)

【讨论】：