用于在restful API中对结果进行高级过滤的URL设计 [英] URL design for advanced filtering of results in restful API

问题描述

让我们举一个通用示例，说明您可以使用 PHP 中内置的 Restful API 建模的资源.

Let's take a generic example of resources you might model with a restful API built in PHP.

• 一个车库有多辆汽车和多个机械师.
• 一辆汽车只有一个车库.
• 一名机械师拥有多辆汽车和多个车库(他是个工作狂，好吧！).

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

So logic says that our endpoints should be

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

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

If we wanted to get all cars of garage 1234 we would use GET /v1/garages/1234/cars

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

If we wanted all cars for mechanic 12 that are in garage 34 we would use GET /v1/mechanics/12/garage/34/cars

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

But what about if we wanted all cars from garages 56 AND 78?
I have a few ideas in mind but the best I can think of is GET /v1/cars?garage=[id=[56,78]]

这将使我们能够从任何涂有黄色油漆和碳盖的车库中获取所有带有两扇或四扇门的绿色汽车GET/v1/cars?garage=[paint=yellow,bonnet=[material=carbon]]&color=green&doors=[2,4]

Which would allow us to grab all green cars with two or four doors from any garages that have yellow paint and carbon bonnets via GET /v1/cars?garage=[paint=yellow,bonnet=[material=carbon]]&color=green&doors=[2,4]

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

Does this seem like a reasonable idea or am I going to run into issues with this getting to complex with the nesting, should this be easy enough to parse with PHP?

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

Another idea I had was Json as far as I am aware all json is valid in a url so

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

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

Which makes it super easy for developers to use then as almost all programming languages now have json support, and on the API end we can just use json_decode($_SERVER[''QUERY_STRING]) so are there any issues with using Json?

第三个想法创建搜索"

我的意思是我们使用

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

POST /cars/search with the above Json as post data that request will simply return the ID of the search to which the results could then be fetched via GET /cars/search/{id} this would alleviate the complexity on my side and avoid the 8kb limit for requests (this is an API, not meant to be used by browser address bars). but I am concerned that if I do this then it defeats the purpose of the top level GET /v1/cars endpoint?

推荐答案

感谢 #laravel irc 频道的热心人士 我与谁进行了长时间的交谈，我们有一个似乎有效的答案.

Thanks to the helpful guys over at the #laravel irc channel who I had rather an extended conversation with we have an answer that seems to work.

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

We chose this answer based on a few thing:

• 易于人类阅读
• 查询的力量
• 平坦度(易于解析)
• 易于过滤

基本请求是

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

结合下面的代码

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

吐出一个像下面这样的数组，可以很容易地在 API 中迭代它来进行过滤:)

Spits out an array like below which can be easily iterated over in the API to do the filtering :)

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

这篇关于用于在restful API中对结果进行高级过滤的URL设计的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！