RESTful URL-Design für die Suche

Question

Ich bin auf der Suche nach einer vernünftigen Möglichkeit, Suchen als RESTful URLs darzustellen.

Der Aufbau: Ich habe zwei Modelle, Autos und Garagen, wobei Autos in Garagen sein können. Meine URLs sehen also so aus:

/car/xxxx
  xxx == car id
  returns car with given id

/garage/yyy
  yyy = garage id
  returns garage with given id

Ein Auto kann allein stehen (daher das /car), oder es kann in einer Garage stehen. Wie kann man nun alle Autos in einer bestimmten Garage darstellen? Etwa so:

/garage/yyy/cars     ?

Wie wäre es mit der Vereinigung der Autos in Garage yyy und zzz?

Wie kann man eine Suche nach Autos mit bestimmten Eigenschaften richtig darstellen? Sprich: Zeige mir alle blauen Limousinen mit 4 Türen:

/car/search?color=blue&type=sedan&doors=4

oder sollte es stattdessen /cars heißen?

Die Verwendung von "Suche" scheint hier unangebracht zu sein - was ist ein besserer Weg / Begriff? Sollte es einfach sein:

/cars/?color=blue&type=sedan&doors=4

Sollten die Suchparameter Teil des PATHINFO oder QUERYSTRING sein?

Kurz gesagt, ich suche eine Anleitung für die modellübergreifende Gestaltung von REST-Url und für die Suche.

[Update] Ich mag Justins Antwort, aber er deckt nicht den Fall der Suche mit mehreren Feldern ab:

/cars/color:blue/type:sedan/doors:4

oder etwas Ähnliches. Wie kommen wir von

/cars/color/blue

auf den Fall mit mehreren Feldern?

Answer 1

Ich verwende zwei Ansätze zur Durchführung von Suchvorgängen.

1) Im einfachsten Fall für die Abfrage verbundener Elemente und für die Navigation.

    /cars?q.garage.id.eq=1

Dies bedeutet, dass Sie Autos abfragen, deren Garagen-ID gleich 1 ist.

Es ist auch möglich, komplexere Suchen zu erstellen:

    /cars?q.garage.street.eq=FirstStreet&q.color.ne=red&offset=300&max=100

Autos in allen Garagen in FirstStreet, die nicht rot sind (3. Seite, 100 Elemente pro Seite).

2) Komplexe Abfragen werden als reguläre Ressourcen betrachtet, die erstellt werden und wiederhergestellt werden können.

    POST /searches  => Create
    GET  /searches/1  => Recover search
    GET  /searches/1?offset=300&max=100  => pagination in search

Der POST-Body für die Erstellung der Suche sieht wie folgt aus:

    {  
       "$class":"test.Car",
       "$q":{
          "$eq" : { "color" : "red" },
          "garage" : {
             "$ne" : { "street" : "FirstStreet" }
          }
       }
    }

Sie basiert auf Grails (Kriterien-DSL): http://grails.org/doc/2.4.3/ref/Domain%20Classes/createCriteria.html

Answer 2

Dies ist nicht REST. Sie können keine URIs für Ressourcen innerhalb Ihrer API definieren. Die Ressourcennavigation muss hypertextgesteuert sein. Es ist in Ordnung, wenn Sie hübsche URIs und eine starke Kopplung wünschen, aber nennen Sie es nicht REST, denn es verstößt direkt gegen die Beschränkungen der RESTful-Architektur.

Siehe dies Artikel vom Erfinder von REST.

Answer 3

Darüber hinaus würde ich auch vorschlagen:

/cars/search/all{?color,model,year}
/cars/search/by-parameters{?color,model,year}
/cars/search/by-vendor{?vendor}

Hier, Search wird als untergeordnete Ressource von Cars Ressource.

Answer 4

Hier gibt es viele gute Optionen für Ihren Fall. Dennoch sollten Sie die Verwendung der POST-Stelle in Betracht ziehen.

Der Query-String ist perfekt für Ihr Beispiel, aber wenn Sie etwas Komplizierteres haben, z. B. eine beliebig lange Liste von Elementen oder boolesche Bedingungen, möchten Sie vielleicht den Beitrag als Dokument definieren, das der Client über POST sendet.

Dies ermöglicht eine flexiblere Beschreibung der Suche und vermeidet die Längenbegrenzung der Server-URL.

Answer 5

RESTful empfiehlt die Verwendung von Verben in URLs nicht /cars/search ist nicht restful. Der richtige Weg zum Filtern/Suchen/Paginieren Ihrer APIs ist die Verwendung von Abfrageparametern. Es kann jedoch Fälle geben, in denen Sie von der Norm abweichen müssen. Wenn Sie zum Beispiel mehrere Ressourcen durchsuchen, müssen Sie etwas wie /search?q=query verwenden.

Sie können durch http://saipraveenblog.wordpress.com/2014/09/29/rest-api-best-practices/ die besten Praktiken für die Entwicklung von RESTful APIs zu verstehen