php - 用于在 restful API 中高级过滤结果的 URL 设计

Question

让我们举一个通用的资源示例，您可以使用 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 ":"碳"}}}

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

第三个想法“创建搜索”

我的意思是我们使用

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

Answer 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
        )
    )
)