URL-Design für die erweiterte Filterung von Ergebnissen in einer RESTful-API

Question

Lassen Sie uns ein generisches Beispiel für Ressourcen betrachten, die Sie mit einer in PHP erstellten RESTful-API modellieren könnten.

• Ein Parkplatz hat mehrere Autos und mehrere Mechaniker.
• Ein Auto hat nur einen Parkplatz.
• Ein Mechaniker hat mehrere Autos und mehrere Garagen (er ist ein Workaholic, okay!).

Also sagt die Logik, dass unsere Endpunkte sein sollten

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

Wenn wir alle Autos des Parkplatzes 1234 erhalten wollten, würden wir verwenden GET /v1/garages/1234/cars

Wenn wir alle Autos für Mechaniker 12, die sich im Parkplatz 34 befinden, haben wollen, würden wir verwenden GET /v1/mechanics/12/garage/34/cars

Aber was ist, wenn wir alle Autos von den Parkplätzen 56 UND 78 wollen?
Ich habe ein paar Ideen im Kopf, aber das Beste, an das ich denken kann, ist GET /v1/cars?garage=[id=[56,78]]

Was es uns ermöglichen würde, alle grünen Autos mit zwei oder vier Türen von allen Parkplätzen zu erhalten, die gelbe Farbe und Carbonhauben haben, über GET /v1/cars?garage=[paint=yellow,bonnet=[material=carbon]]&color=green&doors=[2,4]

Scheint dies eine vernünftige Idee zu sein oder werde ich Probleme damit haben, dass es zu komplex wird mit der Verschachtelung, sollte es mit PHP leicht genug zu analysieren sein?

Eine weitere Idee, die ich hatte, war Json soweit ich weiß, ist jedes Json in einer URL gültig, also

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

Was es für Entwickler super einfach macht zu verwenden, da fast alle Programmiersprachen jetzt Json-Unterstützung haben, und auf der API-Seite können wir einfach json_decode($_SERVER[''QUERY_STRING]) verwenden, also gibt es irgendwelche Probleme bei der Verwendung von Json?

Dritte Idee "eine Suche erstellen"

Damit meine ich, dass wir

POST /cars/search mit dem obigen Json als Post-Daten verwenden. Die Anfrage wird einfach die ID der Suche zurückgeben, auf die dann über GET /cars/search/{id} zugegriffen werden kann. Das würde die Komplexität auf meiner Seite lindern und das 8kb-Limit für Anfragen vermeiden (das ist eine API, die nicht von Browser-Adressleisten verwendet werden soll). Aber ich befürchte, dass, wenn ich das tue, der Sinn des Top-Level-GET /v1/cars-Endpunkts verloren geht?

Answer 1

Danke an die hilfreichen Leute im #laravel IRC-Kanal, mit denen ich ein ziemlich ausführliches Gespräch hatte, haben wir eine Antwort, die zu funktionieren scheint.

Wir haben diese Antwort aufgrund einiger Dinge ausgewählt:

• Einfachheit der menschlichen Lesbarkeit
• Leistungsfähigkeit der Abfragen
• Flachheit (Einfachheit des Parsens)
• Einfachheit des Filterns

Die grundlegende Anfrage wäre

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

Dies ergibt zusammen mit dem folgenden Code

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

Ein Array wie unten, über das in der API leicht iteriert werden kann, um die Filterung durchzuführen :)

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