wake-up-neo.com

Restful-API-Namenskonventionen

Also stimmen mein Chef und ich hier nicht zu und können keine Informationen darüber finden. Szenario: Ich möchte alle Benutzer für eine bestimmte Organisation erhalten. Was soll die URL sein?

mydomain.com/users/by/organisation/{orgId}

OR

mydomain.com/organisation/{orgId}/users

Unsere Argumente: 

Fall 1: Es wird erwartet, dass der Anruf "Benutzer" zurückgibt, und daher sollte sich die "Ressource" (erster Teil des Anrufs) darauf beziehen. 

Fall 2: Die Organisation "besitzt"/"ist das übergeordnete Element" des Benutzers, und daher sollte die Organisation an erster Stelle stehen.

Was sind deine Gedanken?

UPDATE: Ich mache mir keine Sorgen darüber, was nach dem mydomain.com/{resource} kommt. Die Frage bezieht sich meistens darauf, ob die HTTP-Aktion (GET, POST, PUT, DELETE) sich auf die erste Ressource mydomain.com/users bezieht oder ob sie die Beziehung mydomain.com/organisations/users/ widerspiegeln soll.

8
We0

Sie wissen wahrscheinlich, dass REST keine strengen Regeln hat, Sie können es mehr oder weniger frei implementieren, wie Sie möchten, aber hier sind meine 2 Cent

mydomain.com/users/by/organisation/{orgId}

Dies klingt jedoch nach einer guten URL, weil es Ihnen irgendwie sagt, was es tut, wenn Sie es lesen, das ist keine gute Idee. Normalerweise gibt jedes URL-Segment eine Ressource an , die existiert oder existieren kann.

In diesem Fall stellt users eine oder mehrere Ressourcen dar, und zwar organisation, by jedoch nicht. Wahrscheinlich ist es nichts weiter als ein Word, das die Funktionsweise der API deutlich macht.

Es wird erwartet, dass der Aufruf "Benutzer" zurückgibt, und daher sollte sich die "Ressource" (erster Teil des Anrufs) darauf beziehen.

Eine Ressource wird nicht unbedingt im ersten Teil der URL angegeben. Es kann der 2., 3. oder 10. sein, wenn Sie möchten


mydomain.com/organisation/{orgId}/users

Das sieht viel besser aus, aber ich denke, es gibt einen Punkt der Verbesserung. Sie sollten organisation in organisations umbenennen, um users zu entsprechen.

Diese

mydomain.com/organisations/{orgId}

ruft dann die Organisation mit der ID orgId und

mydomain.com/organisations/{orgId}/users

ruft alle Benutzer auf, die zu dieser Organisation gehören.

Um es weiter einzugrenzen, könnten Sie tun

mydomain.com/organisations/{orgId}/users/{userId}

um einen bestimmten Benutzer einer bestimmten Organisation zu erhalten


UPDATE: Ich mache mir keine Sorgen darüber, was nach dem Mydomain.com/{resource} kommt. Die Frage bezieht sich hauptsächlich darauf, ob dieHTTP-Aktion (GET, POST, PUT, DELETE) sollte sich auf die erste beziehenRessource mydomain.com/users oder ob es die Beziehung mydomain.com/organisations/users/ widerspiegeln soll.

So beantworten Sie Ihre Aktualisierung:

Ich habe es oben schon erwähnt; Eine Ressource ist nicht unbedingt im ersten Teil der URL angegeben. . Wenn sich die Qualität der URL durch Verschieben der gewünschten Ressource an der Rückseite der URL verbessert, fahren Sie fort und tun Sie dies

17
Tim Castelijns

Lassen Sie mich damit beginnen: Technisch sollte es eigentlich keine Rolle spielen. REST gibt an, dass URLs über Links auffindbar sein müssen, z. B. Links in normalen (HTML) Webseiten.

Eine konsistente, selbsterklärende URL-Struktur schadet jedoch nicht. Ich würde eine hierarchische Struktur in URLs vorschlagen:

  • /organisations gibt eine Liste aller Organisationen zurück
  • /organisations/123 gibt eine bestimmte Organisation zurück (# 123)
  • /organisations/123/users gibt eine Liste der Benutzer zurück, die dieser Organisation zugeordnet sind
  • usw.

Eine Alternative wäre die Verwendung einer Abfragezeichenfolge zum Filtern:

  • /users gibt eine Liste aller Benutzer zurück
  • /users?organisation=123 gibt eine Liste der Benutzer zurück, die dieser Organisation zugeordnet sind

Aus dieser hierarchischen Perspektive wäre /users/by/organisation/123 nicht sinnvoll. Was wäre das Ergebnis eines Aufrufs von /users/by/organisation? Oder /users/by?

6
Nic Wortel

Es gibt einen konzeptionellen Unterschied zwischen dem, was Sie hier zeigen möchten. Die erste ist eine Filterung aller Benutzerressourcen im System anhand einiger Kriterien. Die zweite zeigt die Benutzerressourcen, die zu einer Organisation gehören.

Die zweite URL ist ok, um Benutzer anzuzeigen, die zu einer Organisation gehören, von der ich denke,.

Die erste URL filtert effektiv die Benutzer, die Sie sehen möchten, von allen Benutzern. 

Die Verwendung der URL ist möglicherweise für die Filterung in Ordnung, obwohl die Verwendung von URL-Abfragen auch in Ordnung ist. so

mydomain.com/users?organisationId={orgId}

könnte vorzuziehen sein. Die URLs können noch Querstrings enthalten und erholsam sein.

Ist DELETE mydomain.com/users/organisation/{orgid} wirklich sinnvoll? Würden Sie damit rechnen, die Organisation zu löschen? Wenn nicht, dann zeigt dies nicht wirklich auf eine Ressource. Daher führen Sie eine Suche durch und sollten Querystrings verwenden.

Es gibt andere Optionen für die Suche, z. B. die Suchkriterien zu einem erstklassigen Objekt zu machen, oder eine der anderen Filtertechniken in diese Frage oder diese Frage verwenden.

6
Sam Holder

mydomain.com/users/by/organisation/{orgId}

Was bedeutet "von"? Das hat nichts mit irgendetwas zu tun. Versuchen Sie, zufällige Wörter aus der URL herauszuhalten .

Fall 1: Es wird erwartet, dass der Anruf "Benutzer" zurückgibt, und daher sollte sich die "Ressource" (erster Teil des Anrufs) darauf beziehen.

Dies ist keine Regel, die RESTful-APIs durchsetzen oder erwarten. Es ist in der Branche auch nicht so üblich, und ich habe mit einer Menge APIs gearbeitet. Betrachten Sie es als Ordner.

  • / Benutzer - eine Liste von Benutzern
  • / users/1 - Benutzer mit der ID 1
  • / Benutzer/1/Organisationen - die Organisationen, zu denen der Benutzer gehört
  • / organisationen - eine Liste von Organisationen
  • / organisationen/1 - organisationsnummer 1
  • / organisations/1/users - Die Benutzer dieser Organisation 

Du betrachtest es wie ein Programmierer, als wäre es SOAP oder eine PHP Funktion, die versucht, getUsersByOrganization($orgId) zu machen, und so funktioniert REST nicht. :)

Wenn Sie sich an Fall 1 halten müssen (erstes URI-Segment = Rückgabetyp), dann führen Sie folgende Schritte aus:

  • / Benutzer? orgId = 1

Das ist perfekt RESTful und es ist im Wesentlichen nur ein Filter. Sie könnten sogar beides tun, aber ich würde nicht. Es ist eine Beziehung, die dort keinen Platz hat. Ich versuche Filter zu behalten wie:? Active = true

2
Phil Sturgeon

Bei REST ist die URI-Struktur nur aus menschlicher Sicht von Bedeutung. Aus der Sicht des REST-Clients spielt dies keine Rolle, da es sich um einen mit Semantik annotierten Link handelt.

Um Ihre Frage zu beantworten, ist es wichtig, was Sie beschreiben möchten, Beziehungen oder Benutzer. Wenn Sie Beziehungen hinzufügen und entfernen möchten, müssen Sie eine Beziehungssammlung definieren. Wenn Sie Benutzer hinzufügen und entfernen möchten, müssen Sie eine Benutzersammlung definieren. Dies ist nur durch Manipulation von Bedeutung. Mit GET können Sie jede Art von Abfrage definieren, die eine Reihe von Benutzern zurückgibt.

0
inf3rno

Der zweite ist besser. Wenn Sie den URI durchgehen, sollte die Anforderung eingeschränkt werden, entweder als Filter oder als Anzeige von übergeordneten Objekten. Benutzer gehören zu einer Organisation, daher sollten es Organisation/Benutzer sein. Aber ich würde, wenn möglich, auch die Organisationsebene der URI loswerden.

mydomain.com/{orgId}/users
0
Pharylon