Best Practices für die REST-API: Wo werden Parameter abgelegt? [geschlossen]

Eine REST-API kann auf mindestens zwei Arten Parameter haben:

1. Als Teil des URL-Pfades (dh /api/resource/parametervalue )
2. Als Abfrageargument (dh /api/resource?parameter=value )

Was ist hier die beste Vorgehensweise? Gibt es allgemeine Richtlinien, wann 1 und wann 2 verwendet werden sollen?

Beispiel aus der Praxis: Twitter verwendet Abfrageparameter zum Festlegen von Intervallen. ( http://api.twitter.com/1/statuses/home_timeline.json?since_id=12345&max_id=54321)

Wäre es besser, diese Parameter in den URL-Pfad einzufügen?

Wenn es dokumentierte Best Practices gibt, habe ich sie noch nicht gefunden. Hier sind jedoch einige Richtlinien, die ich verwende, um zu bestimmen, wo Parameter in eine URL eingefügt werden sollen:

Optionale Parameter lassen sich in der Regel einfacher in die Abfragezeichenfolge einfügen.

Wenn Sie einen 404-Fehler zurückgeben möchten, wenn der Parameterwert keiner vorhandenen Ressource entspricht, würde ich zu einem Pfadsegmentparameter tendieren. zB /customer/232wo 232 keine gültige Kundennummer ist.

Wenn Sie jedoch eine leere Liste zurückgeben möchten, wenn der Parameter nicht gefunden wird, empfehle ich die Verwendung von Abfragezeichenfolgenparametern. z.B/contacts?name=dave

Wenn ein Parameter einen gesamten Teilbaum Ihres URI-Bereichs betrifft, verwenden Sie ein Pfadsegment. zB ein Sprachparameter /en/document/foo.txt versus/document/foo.txt?language=en

Ich bevorzuge eindeutige Bezeichner in einem Pfadsegment anstelle eines Abfrageparameters.

Die offiziellen Regeln für URIs finden Sie in dieser RFC-Spezifikation hier . Es gibt auch eine weitere sehr nützliche RFC spec hier , dass definiert Regeln für die Parametrierung URIs.

Späte Antwort, aber ich werde dem, was geteilt wurde, einige zusätzliche Erkenntnisse hinzufügen, nämlich, dass eine Anfrage verschiedene Arten von "Parametern" enthält, und Sie sollten dies berücksichtigen.

1. Locators - ZB Ressourcenkennungen wie IDs oder Aktion / Ansicht
2. Filter - ZB Parameter, mit denen die Ergebnismenge gesucht, sortiert oder eingegrenzt werden kann.
3. Status - zB Sitzungsidentifikation, API-Schlüssel, was auch immer.
4. Inhalt - ZB zu speichernde Daten.

Schauen wir uns nun die verschiedenen Stellen an, an denen diese Parameter gespeichert werden könnten.

1. Fordern Sie Header und Cookies an
2. URL-Abfragezeichenfolge ("GET" -Vars)
3. URL-Pfade
4. Body Query String / Multipart ("POST" -Vars)

Im Allgemeinen möchten Sie, dass der Status in Headern oder Cookies festgelegt wird, je nachdem, um welche Art von Statusinformationen es sich handelt. Ich denke, wir können uns alle darauf einigen. Verwenden Sie bei Bedarf benutzerdefinierte http-Header (X-My-Header).

In ähnlicher Weise hat Content nur einen Platz, zu dem er gehört, und zwar im Anfragetext, entweder als Abfragezeichenfolgen oder als http-Multipart- und / oder JSON-Inhalt. Dies stimmt mit dem überein, was Sie vom Server erhalten, wenn er Ihnen Inhalte sendet. Sie sollten also nicht unhöflich sein und es anders machen.

Locators wie "id = 5" oder "action = refresh" oder "page = 2" sind als URL-Pfad sinnvoll, z. B. mysite.com/article/5/page=2wenn Sie teilweise wissen, was jedes Teil bedeuten soll (Grundlagen wie Artikel und 5 bedeutet natürlich, dass ich die Daten vom Typ Artikel mit der ID 5) bekomme und zusätzliche Parameter als Teil der URI angegeben werden. Sie können in Form von page=2oder page/2wenn Sie wissen, dass nach einem bestimmten Punkt in der URI die "Ordner" gepaarte Schlüsselwerte sind.

Filter werden immer in die Abfragezeichenfolge eingefügt, da sie zwar Teil der Suche nach den richtigen Daten sind, jedoch nur dazu dienen, eine Teilmenge oder Änderung dessen zurückzugeben, was die Locators allein zurückgeben. Die Suche in mysite.com/article/?query=Obama(Teilmenge) ist ein Filter, ebenso wie /article/5?order=backwards(Modifikation). Überlegen Sie, was es tut, nicht nur, wie es heißt!

Wenn "view" das Ausgabeformat bestimmt, handelt es sich um einen filter ( mysite.com/article/5?view=pdf), da er eine Änderung der gefundenen Ressource zurückgibt, anstatt auf die gewünschte Ressource zuzugreifen. Wenn es stattdessen entscheidet, welchen bestimmten Teil des Artikels wir sehen ( mysite.com/article/5/view=summary), ist es ein Locator.

Denken Sie daran, dass das Eingrenzen einer Reihe von Ressourcen gefiltert wird. Wenn Sie etwas Bestimmtes innerhalb einer Ressource suchen, suchen Sie ... duh. Die Teilmengenfilterung kann eine beliebige Anzahl von Ergebnissen zurückgeben (sogar 0). Beim Auffinden wird immer die bestimmte Instanz von etwas gefunden (falls vorhanden). Bei der Änderungsfilterung werden dieselben Daten wie beim Locator zurückgegeben, außer bei Änderungen (sofern eine solche Änderung zulässig ist).

Ich hoffe, dies hat den Leuten einige Eureka-Momente beschert, wenn sie sich nicht sicher sind, wo sie etwas unterbringen sollen!

Es kommt auf ein Design an. Es gibt keine Regeln für URIs bei REST über HTTP (Hauptsache, sie sind eindeutig). Oft geht es um Geschmack und Intuition ...

Ich gehe folgendermaßen vor:

• URL-Pfadelement: Die Ressource und ihr Pfadelement bilden eine Verzeichnisdurchquerung und eine Unterressource (z. B. / items / {id}, / users / items). Wenn Sie sich nicht sicher sind, fragen Sie Ihre Kollegen, ob sie der Meinung sind, dass das Durchqueren und das Denken in einem "anderen Verzeichnis" höchstwahrscheinlich das richtige Pfadelement ist
• URL-Parameter: Wenn es wirklich keine Durchquerung gibt (Suchressourcen mit mehreren Abfrageparametern sind ein sehr schönes Beispiel dafür).

IMO sollten die Parameter als Abfrageargumente besser sein. Die URL wird verwendet, um die Ressource zu identifizieren, während die hinzugefügten Abfrageparameter angeben, welchen Teil der Ressource Sie möchten, welchen Status die Ressource haben soll usw.

Gemäß der REST-Implementierung

1) Pfadvariablen werden für die direkte Aktion auf die Ressourcen verwendet, z. B. ein Kontakt oder ein Lied, z. B.
GET usw. / api / resource / {songid} oder
GET usw. / api / resource / { contactid} geben die entsprechenden Daten zurück.

2) Abfrage-Dauerwellen / Argumente werden für die direkten Ressourcen wie Metadaten eines Songs verwendet, z. B. GET / api / resource / {songid}? Metadata = genres. Es werden die Genre-Daten für diesen bestimmten Song zurückgegeben.

"Packen" und POSTEN Sie Ihre Daten gegen den "Kontext", den der Universumsressourcen-Locator bereitstellt, was für den Locator die Nummer 1 bedeutet.

Beachten Sie die Einschränkungen mit # 2. Ich bevorzuge POSTs gegenüber # 1.

Hinweis: Einschränkungen werden für diskutiert

POST in Gibt es eine maximale Größe für den Inhalt von POST-Parametern?

GET in Gibt es eine Begrenzung für die Länge einer GET-Anforderung? und Maximale Größe der URL-Parameter in _GET

ps Diese Grenzwerte basieren auf den Clientfunktionen (Browser) und dem Server (Konfiguration).

Gemäß dem URI-Standard bezieht sich der Pfad auf hierarchische Parameter und die Abfrage auf nicht hierarchische Parameter. Ofc. Es kann sehr subjektiv sein, was für Sie hierarchisch ist.

In Situationen, in denen mehrere URIs derselben Ressource zugewiesen sind, möchte ich die zur Identifizierung erforderlichen Parameter in den Pfad und die zum Erstellen der Darstellung erforderlichen Parameter in die Abfrage einfügen. (Für mich ist es auf diese Weise einfacher zu routen.)

Zum Beispiel:

• /users/123 und /users/123?fields="name, age"
• /users und /users?name="John"&age=30

Für die Kartenreduzierung verwende ich gerne die folgenden Ansätze:

• /users?name="John"&age=30
• /users/name:John/age:30

Es liegt also wirklich an Ihnen (und Ihrem serverseitigen Router), wie Sie Ihre URIs erstellen.

Hinweis: Nur um diese Parameter zu erwähnen, handelt es sich um Abfrageparameter. Sie definieren also wirklich eine einfache Abfragesprache. Bei komplexen Abfragen (die Operatoren wie und oder oder größer als usw. enthalten) empfehle ich Ihnen, eine bereits vorhandene Abfragesprache zu verwenden. Die Funktionen von URI-Vorlagen sind sehr begrenzt ...

Als Programmierer auf Client-Seite bevorzuge ich das Abfrageargument. Außerdem trennt es für mich den URL-Pfad von den Parametern, erhöht die Übersichtlichkeit und bietet mehr Erweiterbarkeit. Außerdem kann ich eine separate Logik zwischen dem URL / URI-Gebäude und dem Parameter-Builder verwenden.

Mir gefällt, was Manuel Aldana über die andere Option gesagt hat, wenn es sich um eine Art Baum handelt. Ich kann sehen, dass benutzerspezifische Teile so entfernt werden.

Es gibt keine festen Regeln, aber die Faustregel aus rein konzeptioneller Sicht, die ich gerne verwende, lässt sich kurz so zusammenfassen: Ein URI-Pfad (per Definition) stellt eine Ressource dar, und Abfrageparameter sind im Wesentlichen Modifikatoren für diese Ressource . So weit , dass wahrscheinlich nicht hilft ... Mit einer REST - API haben Sie die wichtigsten Methoden der auf eine einzelne Ressource wirkt mit GET, PUTund DELETE. Daher kann reduziert werden, ob etwas im Pfad oder als Parameter dargestellt werden soll, ob diese Methoden für die betreffende Darstellung sinnvoll sind. Würden Sie vernünftigerweise PUTetwas auf diesem Weg tun und wäre es semantisch sinnvoll , dies zu tun? Das könntest du natürlichPUT fast überall etwas tun und das Back-End biegen, um damit umzugehen, aber Sie sollten es seinPUTwas einer Darstellung der tatsächlichen Ressource und nicht einer unnötig kontextualisierten Version davon gleichkommt. Für Sammlungen kann das gleiche mit gemacht werden POST. Wenn Sie einer bestimmten Sammlung hinzufügen möchten, welche URL wäre sinnvoll POST.

Dies lässt immer noch einige Grauzonen übrig, da einige Pfade darauf hinweisen könnten, wie viel Kinder von Elternressourcen betroffen sind, was etwas diskretionär ist und von ihrer Verwendung abhängt. Die einzige harte Linie, die dies zeichnet, ist, dass jede Art von transitiver Darstellung unter Verwendung eines Abfrageparameters erfolgen sollte, da keine zugrunde liegende Ressource vorhanden wäre.

In Reaktion auf das Beispiel der realen Welt in der ursprünglichen Frage (Twitter-API) stellen die Parameter eine transitive Abfrage dar, die nach dem Status der Ressourcen (und nicht nach einer Hierarchie) filtert. In diesem speziellen Beispiel wäre es völlig unvernünftig, die durch diese Einschränkungen dargestellte Sammlung zu erweitern, und außerdem könnte diese Abfrage nicht als Pfad dargestellt werden, der im Sinne eines Objektgraphen sinnvoll wäre.

Die Verwendung dieser Art von ressourcenorientierter Perspektive kann leicht direkt auf das Objektdiagramm Ihres Domänenmodells abgebildet werden und die Logik Ihrer API so weit bringen, dass alles sehr sauber und ziemlich selbstdokumentierend funktioniert, sobald es klar wird. Das Konzept kann auch klarer gemacht werden, indem Sie sich von Systemen entfernen, die traditionelles URL-Routing verwenden, das einem normalerweise nicht passenden Datenmodell (dh einem RDBMS) zugeordnet ist. Apache Sling wäre sicherlich ein guter Anfang. Das Konzept des Objektdurchlaufversands in einem System wie Zope bietet auch ein klareres Analogon.

Hier ist meine Meinung.

Abfrageparameter werden als Metadaten für eine Anforderung verwendet. Sie fungieren als Filter oder Modifikator für einen vorhandenen Ressourcenaufruf.

Beispiel:

/calendar/2014-08-08/events

sollte Kalenderereignisse für diesen Tag geben.

Wenn Sie Ereignisse für eine bestimmte Kategorie wünschen

/calendar/2014-08-08/events?category=appointments

oder wenn Sie Ereignisse von mehr als 30 Minuten benötigen

/calendar/2014-08-08/events?duration=30

Ein Lackmustest wäre zu prüfen, ob die Anfrage noch ohne Abfrageparameter bearbeitet werden kann.

Ich tendiere im Allgemeinen zu # 2 als Abfrageargument (dh / api / resource? Parameter = Wert).

Eine dritte Möglichkeit besteht darin, den Parameter = value tatsächlich im Body zu veröffentlichen.

Dies liegt daran, dass es für Ressourcen mit mehreren Parametern besser funktioniert und für die zukünftige Verwendung erweiterbarer ist.

Egal für welches Sie sich entscheiden, stellen Sie sicher, dass Sie nur eines auswählen, nicht mischen und anpassen. Das führt zu einer verwirrenden API.

Eine "Dimension" dieses Themas wurde weggelassen, aber es ist sehr wichtig: Es gibt Zeiten, in denen die "Best Practices" mit der Plattform, die wir implementieren oder mit REST-Funktionen erweitern, in Einklang gebracht werden müssen.

Praktisches Beispiel:

Viele Webanwendungen implementieren heutzutage die MVC-Architektur (Model, View, Controller). Sie gehen davon aus, dass ein bestimmter Standardpfad bereitgestellt wird, insbesondere dann, wenn diese Webanwendungen mit der Option "SEO-URLs aktivieren" ausgestattet sind.

Um nur eine ziemlich berühmte Webanwendung zu erwähnen: einen OpenCart E-Commerce-Shop. Wenn der Administrator die "SEO-URLs" aktiviert, erwartet er, dass diese URLs in einem ganz normalen MVC-Format vorliegen, wie:

http://www.domain.tld/special-offers/list-all?limit=25

Wo

• special-offers ist der MVC-Controller, der die URL verarbeiten soll (mit der Seite mit den Sonderangeboten).

• list-allist der aufzurufende Aktions- oder Funktionsname des Controllers. (*)

• limit = 25 ist eine Option, die besagt, dass 25 Elemente pro Seite angezeigt werden.

(*) list-allist ein fiktiver Funktionsname, den ich aus Gründen der Übersichtlichkeit verwendet habe. In der Realität verfügen OpenCart und die meisten MVC-Frameworks über eine implizite Standardfunktion (die normalerweise in der URL weggelassen wird) index, die aufgerufen wird, wenn der Benutzer eine Standardaktion ausführen möchte. Die URL der realen Welt wäre also:

http://www.domain.tld/special-offers?limit=25

Mit einer mittlerweile ziemlich standardmäßigen Anwendungs- oder Framework-Struktur, die der oben genannten ähnelt, erhalten Sie häufig einen Webserver, der dafür optimiert ist und URLs dafür neu schreibt (die wahre "nicht SEOed URL" wäre :) http://www.domain.tld/index.php?route=special-offers/list-all&limit=25.

Daher müssen Sie als Entwickler mit der vorhandenen Infrastruktur umgehen und Ihre "Best Practices" anpassen, es sei denn, Sie sind der Systemadministrator. Sie wissen genau, wie Sie eine Apache / NGinx-Umschreibekonfiguration optimieren (letztere kann unangenehm sein!) Und so weiter auf.

Daher ist Ihre REST-API häufig viel besser, wenn Sie den Standards der verweisenden Webanwendung folgen, sowohl aus Gründen der Konsistenz als auch der Einfachheit / Geschwindigkeit (und damit der Budgetersparnis).

Um zum obigen praktischen Beispiel zurückzukehren, wäre eine konsistente REST-API etwas mit URLs wie:

http://www.domain.tld/api/special-offers-list?from=15&limit=25

oder (nicht SEO URLs)

http://www.domain.tld/index.php?route=api/special-offers-list?from=15&limit=25

mit einer Mischung aus Argumenten "Pfade gebildet" und Argumenten "Abfrage gebildet".

Ich sehe viele REST-APIs, die Parameter nicht gut verarbeiten. Ein häufig auftretendes Beispiel ist, wenn der URI personenbezogene Daten enthält.

http://software.danielwatrous.com/design-principles-for-rest-apis/

Ich denke, eine Folgefrage ist, wann ein Parameter überhaupt kein Parameter sein sollte, sondern stattdessen in den HEADER oder BODY der Anfrage verschoben werden sollte .

Das ist eine sehr interessante Frage.

Sie können beide verwenden, es gibt keine strengen Regeln zu diesem Thema, aber die Verwendung von URI-Pfadvariablen hat einige Vorteile:

• Cache : Die meisten Web-Cache-Dienste im Internet speichern GET-Anforderungen nicht zwischen, wenn sie Abfrageparameter enthalten. Sie tun dies, weil es viele RPC-Systeme gibt, die GET-Anforderungen verwenden, um Daten auf dem Server zu ändern (fehlgeschlagen !! Get muss eine sichere Methode sein).

Wenn Sie jedoch Pfadvariablen verwenden, können alle diese Dienste Ihre GET-Anforderungen zwischenspeichern.

• Hierarchie : Die Pfadvariablen können die Hierarchie darstellen: / Stadt / Straße / Ort

Es gibt dem Benutzer mehr Informationen über die Struktur der Daten.

Wenn Ihre Daten jedoch keine Hierarchiebeziehung haben, können Sie weiterhin Pfadvariablen mit Komma oder Semikolon verwenden:

/ Stadt / Längengrad, Breitengrad

Verwenden Sie in der Regel Komma, wenn die Reihenfolge der Parameter wichtig ist, und Semikolon, wenn die Reihenfolge keine Rolle spielt:

/ IconGenerator / rot; blau; grün

Abgesehen von diesen Gründen gibt es einige Fälle, in denen häufig Abfragezeichenfolgenvariablen verwendet werden:

• Wenn der Browser automatisch HTML-Formularvariablen in den URI einfügen muss
• Wenn Sie mit Algorithmus zu tun haben. Beispielsweise verwendet die Google Engine Abfragezeichenfolgen:

http: // www.google.com/search?q=rest

Zusammenfassend lässt sich sagen, dass es keinen triftigen Grund gibt, eine dieser Methoden zu verwenden, aber wann immer Sie können, verwenden Sie URI-Variablen.