Ich suche nach einer vernünftigen Möglichkeit, Suchanfragen als RESTful-URLs darzustellen.

Das Setup: Ich habe zwei Modelle, Autos und Garagen, bei denen 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 alleine existieren (daher das / Auto) oder es kann in einer Garage existieren. Was ist der richtige Weg, um beispielsweise alle Autos in einer bestimmten Garage darzustellen? Etwas wie:

/garage/yyy/cars     ?

Wie wäre es mit der Vereinigung von Autos in Garage JJJ und ZZZ?

Wie kann eine Suche nach Autos mit bestimmten Attributen richtig dargestellt werden? Sprich: Zeig mir alle blauen Limousinen mit 4 Türen:

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

oder sollte es stattdessen / autos sein?

Die Verwendung von "Suche" scheint dort unangemessen - was ist ein besserer Weg / Begriff? Sollte es nur sein:

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

Sollten die Suchparameter Teil von PATHINFO oder QUERYSTRING sein?

Kurz gesagt, ich suche nach Anleitungen für das modellübergreifende REST-URL-Design und für die Suche.

[Update] Ich mag Justins Antwort, aber er behandelt den Mehrfeld-Suchfall nicht:

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

oder etwas ähnliches. Wie gehen wir weiter?

/cars/color/blue

zum Mehrfeldfall?

Verwenden Sie für die Suche Querystringe. Das ist vollkommen RESTful:

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

Ein Vorteil von regulären Abfrageringen besteht darin, dass sie Standard sind und allgemein verstanden werden und dass sie aus Form-Get generiert werden können.

Beim hübschen RESTful-URL-Design geht es darum, eine Ressource basierend auf einer Struktur anzuzeigen (verzeichnisähnliche Struktur, Datum: Artikel / 2005/5/13, Objekt und seine Attribute, ..). Der Schrägstrich /zeigt eine hierarchische Struktur an-id stattdessen die.

Hierarchische Struktur

Ich persönlich würde es vorziehen:

/garage-id/cars/car-id
/cars/car-id   #for cars not in garages

Wenn ein Benutzer das /car-idTeil entfernt, wird die carsVorschau angezeigt - intuitiv. Der Benutzer weiß genau, wo er sich im Baum befindet und worauf er schaut. Er weiß vom ersten Blick an, dass Garagen und Autos in Beziehung stehen. /car-idbedeutet auch, dass es im Gegensatz zu zusammen gehört/car/id .

Suchen

Die Suchabfrage ist in Ordnung , es gibt nur Ihre Präferenz, was berücksichtigt werden sollte. Der lustige Teil kommt beim Beitreten zu Suchanfragen (siehe unten).

/cars?color=blue;type=sedan   #most prefered by me
/cars;color-blue+doors-4+type-sedan   #looks good when using car-id
/cars?color=blue&doors=4&type=sedan   #I don't recommend using &*

Oder im Grunde alles, was kein Schrägstrich ist, wie oben erklärt.
Die Formel : /cars[?;]color[=-:]blue[,;+&], * obwohl ich das &Zeichen nicht verwenden würde , da es auf den ersten Blick nicht aus dem Text erkennbar ist.

** **. Wussten Sie, dass das Übergeben eines JSON-Objekts in URI RESTful ist? ** **.

Liste der Optionen

/cars?color=black,blue,red;doors=3,5;type=sedan   #most prefered by me
/cars?color:black:blue:red;doors:3:5;type:sedan
/cars?color(black,blue,red);doors(3,5);type(sedan)   #does not look bad at all
/cars?color:(black,blue,red);doors:(3,5);type:sedan   #little difference

mögliche Funktionen?

Suchzeichenfolgen negieren (!)
So suchen Sie nach Autos, aber nicht nach Schwarz und Rot :
?color=!black,!red
color:(!black,!red)

Neues Profil Suchen
Suchen rot oder blau oder schwarz Autos mit 3 Türen in Garagen ID 1..20 oder 101..103 oder 999 , aber nicht 5 /garage[id=1-20,101-103,999,!5]/cars[color=red,blue,black;doors=3]
Sie können dann komplexere Suchanfragen konstruieren. (Schauen Sie sich die CSS3-Attributübereinstimmung an, um die Idee zum Abgleichen von Teilzeichenfolgen zu finden. Suchen Sie beispielsweise nach Benutzern, die "bar" enthalten.user*=bar .)

Fazit

Auf jeden Fall könnte dies der wichtigste Teil für Sie sein, denn Sie können es tun, wie Sie möchten. Denken Sie jedoch daran, dass RESTful URI eine Struktur darstellt, die leicht zu verstehen ist, z. B. verzeichnisartig /directory/file./collection/node/item , Daten /articles/{year}/{month}/{day}.. Und wenn man weglassen In jedem der letzten Segmente wissen Sie sofort, was Sie erhalten.

Also .., alle diese Zeichen dürfen nicht codiert werden :

• vorbehaltlos: a-zA-Z0-9_.-~
  Regel zulässig, sowohl codiert als auch nicht, sind beide Verwendungen gleichwertig.
• spezielle Charaktere: $-_.+!*'(),
• reserviert: ;/?:@=&
  Kann für den von ihnen dargestellten Zweck unverschlüsselt verwendet werden, andernfalls müssen sie verschlüsselt werden.

• unsicher: <>"#%{}|\^~[]`
  Warum unsicher und warum sollte lieber codiert werden: RFC 1738 siehe 2.2

  Weitere Zeichenklassen finden Sie auch in RFC 1738 # Seite 20 .

RFC 3986 siehe 2.2
Trotz allem, was ich zuvor gesagt habe, gibt es hier eine allgemeine Unterscheidung von Begrenzern, was bedeutet, dass einige " wichtiger " sind als andere.

• generische Begrenzer: :/?#[]@
• Unterbegrenzer: !$&'()*+,;=

Weitere Informationen:
Hierarchie: siehe 2.3 , siehe 1.2.3
URL-Pfadparametersyntax
CSS3-Attributübereinstimmung
IBM: RESTful Web Services - Die Grundlagen
Hinweis: RFC 1738 wurde von RFC 3986 aktualisiert

Obwohl es einige Vorteile hat, die Parameter im Pfad zu haben, gibt es IMO einige überwiegende Faktoren.

• Nicht alle für eine Suchabfrage benötigten Zeichen sind in einer URL zulässig. Die meisten Interpunktions- und Unicode-Zeichen müssten als Abfragezeichenfolgenparameter URL-codiert sein. Ich ringe mit dem gleichen Problem. Ich möchte XPath in der URL verwenden, aber nicht alle XPath-Syntax ist mit einem URI-Pfad kompatibel. Für einfache Pfade /cars/doors/driver/lock/combinationwäre es daher angebracht, das combinationElement ' ' im XML-Dokument der Fahrertür zu lokalisieren . Ist /car/doors[id='driver' and lock/combination='1234']aber nicht so freundlich.

• Es gibt einen Unterschied zwischen dem Filtern einer Ressource anhand eines ihrer Attribute und dem Angeben einer Ressource.

  Zum Beispiel seit

  /cars/colors Gibt eine Liste aller Farben für alle Autos zurück (die zurückgegebene Ressource ist eine Sammlung von Farbobjekten).

  /cars/colors/red,blue,green würde eine Liste von Farbobjekten zurückgeben, die rot, blau oder grün sind, keine Sammlung von Autos.

  Um Autos zurückzugeben, wäre der Weg

  /cars?color=red,blue,green oder /cars/search?color=red,blue,green

• Parameter im Pfad sind schwieriger zu lesen, da Name / Wert-Paare nicht vom Rest des Pfads isoliert sind, bei dem es sich nicht um Name / Wert-Paare handelt.

Ein letzter Kommentar. Ich bevorzuge /garages/yyy/cars(immer Plural) /garage/yyy/cars(vielleicht war es ein Tippfehler in der ursprünglichen Antwort), weil es vermeidet, den Pfad zwischen Singular und Plural zu ändern. Bei Wörtern mit einem hinzugefügten 's' ist die Änderung nicht so schlecht, aber das Ändern /person/yyy/friendsin /people/yyyscheint umständlich zu sein.

Um Peters Antwort zu erweitern, könnten Sie Search zu einer erstklassigen Ressource machen:

POST    /searches          # create a new search
GET     /searches          # list all searches (admin)
GET     /searches/{id}     # show the results of a previously-run search
DELETE  /searches/{id}     # delete a search (admin)

Die Suchressource enthält Felder für Farbe, Modell erstellen, Garagenstatus usw. und kann in XML, JSON oder einem anderen Format angegeben werden. Wie bei der Ressource Auto und Garage können Sie den Zugriff auf Suchvorgänge basierend auf der Authentifizierung einschränken. Benutzer, die häufig dieselben Suchvorgänge ausführen, können sie in ihren Profilen speichern, sodass sie nicht neu erstellt werden müssen. Die URLs sind so kurz, dass sie in vielen Fällen problemlos per E-Mail gehandelt werden können. Diese gespeicherten Suchvorgänge können die Grundlage für benutzerdefinierte RSS-Feeds usw. sein.

Es gibt viele Möglichkeiten, Suchen zu verwenden, wenn Sie sie als Ressourcen betrachten.

Die Idee wird in diesem Railscast näher erläutert .

Justins Antwort ist wahrscheinlich der richtige Weg, obwohl es in einigen Anwendungen sinnvoll sein kann, eine bestimmte Suche als eigenständige Ressource zu betrachten, z. B. wenn Sie benannte gespeicherte Suchvorgänge unterstützen möchten:

/search/{searchQuery}

oder

/search/{savedSearchName}

Ich verwende zwei Ansätze, um Suchvorgänge zu implementieren.

1) Einfachster Fall, um zugeordnete Elemente abzufragen und zur Navigation.

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

Dies bedeutet, dass Fahrzeuge mit einer Garagen-ID von 1 abgefragt werden müssen.

Es ist auch möglich, komplexere Suchvorgänge 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-Text für die Sucherstellung lautet wie folgt:

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

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

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

Siehe diesen Artikel des Erfinders von REST.

Obwohl mir Justins Antwort gefällt, ist sie meiner Meinung nach eher ein Filter als eine Suche. Was ist, wenn ich etwas über Autos mit Namen wissen möchte, die mit cam beginnen?

So wie ich es sehe, können Sie es in den Umgang mit bestimmten Ressourcen einbauen:
/ cars / cam *

Oder Sie können es einfach in den Filter einfügen:
/ cars / door / 4 / name / cam * / colours / red, blau, grün

Ich persönlich bevorzuge letzteres, bin aber keineswegs ein Experte für REST (nachdem ich erst vor ungefähr zwei Wochen davon gehört habe ...)

RESTful empfiehlt nicht, Verben in URLs zu verwenden. / Cars / search ist nicht erholsam. Der richtige Weg zum Filtern / Suchen / Paginieren Ihrer APIs sind Abfrageparameter. Es kann jedoch Fälle geben, in denen Sie die Norm brechen müssen. Wenn Sie beispielsweise über mehrere Ressourcen hinweg suchen, müssen Sie so etwas wie / search? Q = query verwenden

Unter http://saipraveenblog.wordpress.com/2014/09/29/rest-api-best-practices/ finden Sie die Best Practices für das Entwerfen von RESTful-APIs

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 Searchwird als untergeordnete Ressource der CarsRessource betrachtet.

Hier gibt es viele gute Möglichkeiten für Ihren Fall. Sie sollten dennoch in Betracht ziehen, den POST-Body zu verwenden.

Die Abfragezeichenfolge ist perfekt für Ihr Beispiel. Wenn Sie jedoch etwas Komplizierteres haben, z. B. eine beliebig lange Liste von Elementen oder boolesche Bedingungen, möchten Sie den Beitrag möglicherweise als Dokument definieren, das der Client über POST sendet.

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

Mein Rat wäre:

/garages
  Returns list of garages (think JSON array here)
/garages/yyy
  Returns specific garage
/garage/yyy/cars
  Returns list of cars in garage
/garages/cars
  Returns list of all cars in all garages (may not be practical of course)
/cars
  Returns list of all cars
/cars/xxx
  Returns specific car
/cars/colors
  Returns lists of all posible colors for cars
/cars/colors/red,blue,green
  Returns list of cars of the specific colors (yes commas are allowed :) )

Bearbeiten:

/cars/colors/red,blue,green/doors/2
  Returns list of all red,blue, and green cars with 2 doors.
/cars/type/hatchback,coupe/colors/red,blue,green/
  Same idea as the above but a lil more intuitive.
/cars/colors/red,blue,green/doors/two-door,four-door
  All cars that are red, blue, green and have either two or four doors.

Hoffentlich kommt Ihnen das auf die Idee. Im Wesentlichen sollte Ihre Rest-API leicht erkennbar sein und Ihnen das Durchsuchen Ihrer Daten ermöglichen. Ein weiterer Vorteil bei der Verwendung von URLs und nicht von Abfragezeichenfolgen besteht darin, dass Sie die auf dem Webserver vorhandenen nativen Caching-Mechanismen für den HTTP-Verkehr nutzen können.

Hier ist ein Link zu einer Seite, die die Übel von Abfragezeichenfolgen in REST beschreibt: http://web.archive.org/web/20070815111413/http://rest.blueoxen.net/cgi-bin/wiki.pl?QueryStringsConsideredHarmful

Ich habe den Google-Cache verwendet, weil die normale Seite für mich nicht funktioniert hat. Hier ist auch dieser Link: http://rest.blueoxen.net/cgi-bin/wiki.pl?QueryStringsConsideredHarmful