apiaryio / api-blueprint

API Blueprint
https://apiblueprint.org
MIT License
8.63k stars 2.14k forks source link

How to describe urls with ordered indexed array? #423

Open denisvmedia opened 6 years ago

denisvmedia commented 6 years ago

Here is an example url (I tried to describe it with with both OpenAPI and API BluePrint but failed):

http://example.com/api/items?filter[0][field]=value1&filter[0][type]=gte&filter[0][x]=490&filter[1][field]=value2&filter[1][type]=lte&filter[1][x]=200&filter[2][field]=value3&filter[2][type]=between&filter[2][x]=100&filter[2][y]=300

Some additional notes: we have an array of filters that should accept some values. The parameters can be represented in JSON like this:

[
  {
    "field": "value1",
    "type": "gte",
    "x": 490
  },
  {
    "field": "value2",
    "type": "lte",
    "x": 200
  },
  {
    "field": "value3",
    "type": "between",
    "x": 100,
    "y": 300
  }
]

With this type of query parameters indexing we get natural arrays in PHP without any additional "movements" using something like this:

parse_str('filter[0][field]=value1&filter[0][type]=gte&filter[0][x]=490&filter[1][field]=value2&filter[1][type]=lte&filter[1][x]=200&filter[2][field]=value3&filter[2][type]=between&filter[2][x]=100&filter[2][y]=300', $result);
var_dump($result);
/** output:
array(1) {
  ["filter"]=>
  array(3) {
    [0]=>
    array(3) {
      ["field"]=>
      string(6) "value1"
      ["type"]=>
      string(3) "gte"
      ["x"]=>
      string(3) "490"
    }
    [1]=>
    array(3) {
      ["field"]=>
      string(6) "value2"
      ["type"]=>
      string(3) "lte"
      ["x"]=>
      string(3) "200"
    }
    [2]=>
    array(4) {
      ["field"]=>
      string(6) "value3"
      ["type"]=>
      string(7) "between"
      ["x"]=>
      string(3) "100"
      ["y"]=>
      string(3) "300"
    }
  }
}
**/

So, this is not something exotic, this is a normal php-style query uri.