Ich habe eine Frage zum REST-URL-Design. Ich habe hier einige relevante Beiträge gefunden: Verschiedene RESTful-Darstellungen derselben Ressource und hier: RESTful-URL zur GET-Ressource nach verschiedenen Feldern, aber die Antworten sind nicht ganz klar, was die Best Practices sind und warum. Hier ist ein Beispiel.
Ich habe REST-URLs zur Darstellung der Ressource "Benutzer". Ich kann einen Benutzer mit einer ID oder einer E-Mail-Adresse abrufen, aber die URL-Darstellung bleibt für beide gleich. Ich gehe viele Blogs und Bücher durch und sehe, dass die Leute dies auf viele verschiedene Arten getan haben. Beispielsweise
Lesen Sie diese Übung in einem Buch und irgendwo im Stackoverflow (ich kann den Link anscheinend nicht wiederfinden).
GET /users/id={id}
GET /users/email={email}
Lesen Sie diese Praxis in vielen Blogs
GET /users/{id}
GET /users/email/{email}
Abfrageparameter werden normalerweise zum Filtern der Ergebnisse der durch die URL dargestellten Ressourcen verwendet, aber ich habe gesehen, dass diese Vorgehensweise auch verwendet wird
GET /users?id={id}
GET /users?email={email}
Meine Frage ist, welche von all diesen Praktiken für Entwickler, die die API konsumieren, am sinnvollsten ist und warum? Ich glaube, es gibt keine in Stein gemeißelten Regeln, wenn es um REST-URL-Designs und Namenskonventionen geht, aber ich wollte nur wissen, welchen Weg ich einschlagen sollte, um Entwicklern zu helfen, die APIs besser zu verstehen.
Alle Hilfe geschätzt!
quelle
Antworten:
Nach meiner Erfahrung
GET /users/{id} GET /users/email/{email}
ist der häufigste Ansatz. Ich würde auch erwarten, dass die Methoden einen 404 Not Found zurückgeben, wenn ein Benutzer mit dem bereitgestelltenid
oder nicht existiertemail
. Ich wäre auch nicht überrascht zu sehenGET /users/id/{id}
(obwohl es meiner Meinung nach überflüssig ist).Kommentare zu den anderen Ansätzen
GET /users/id={id} GET /users/email={email}
GET /users?id={id} GET /users?email={email}
id
als auch mit einememail
(z. B.GET /users?id={id}&email={email}
) aufzurufen ? Wenn nicht, würde ich keine einzige Ressourcenmethode wie diese verwenden.id
,email
dass eine eindeutige Kennung zu den Parametern gehört. Beispiel:GET /users?status=BANNED
Gibt möglicherweise eine Liste der gesperrten Benutzer zurück.Überprüfen Sie diese Antwort von einer verwandten Frage.
quelle
/users/id/{id}
, ermöglicht dies eine erweiterte Funktionalität und ermöglicht einfach den Zugriff auf eine Ressource über mehrere Bezeichner (ID, Guid, Name). auch hierGET /user/1234
und nichtGET /users/123
Wenn Sie dies pragmatisch betrachten, haben Sie eine Sammlung von Benutzern:
Jeder Benutzer hat einen dedizierten Ressourcenstandort:
Sie haben auch eine Reihe von Möglichkeiten, nach Benutzern zu suchen:
Da dies alles Abfrageparameter für / Benutzer sind, sollten sie alle Listen zurückgeben. Auch wenn es sich um eine Liste von 1 handelt.
Ich habe hier einen Blog-Beitrag über pragmatisches RESTful-API-Design geschrieben, der unter anderem hier darüber spricht: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
quelle
Informationen zu den Benutzerressourcen
Auf dem Pfad erhalten
/users
Sie immer eine Sammlung von zurückgegebenen Benutzerressourcen.Auf dem Weg können
/users/[user_id]
Sie verschiedene Dinge erwarten:Jeder Singleton wird durch seinen Pfad und seine Kennung eindeutig identifiziert, und Sie verwenden diese, um die Ressource zu finden. Es ist nicht möglich, mehrere Pfade für den Singleton zu verwenden.
Sie können den Pfad
/users
mit Abfrageparametern (GET
Parametern) abfragen . Dadurch wird eine Sammlung mit Benutzern zurückgegeben, die die angeforderten Kriterien erfüllen. Die zurückgegebene Sammlung sollte die Benutzerressourcen enthalten, alle mit ihrem identifizierenden Ressourcenpfad in der Antwort.Parameter können jedes Feld sein, das in den Ressourcen der Sammlung vorhanden ist.
firstName
,lastName
,id
Über die E-Mail
Die E-Mail kann entweder eine Ressource oder eine Eigenschaft / ein Feld der Benutzerressource sein.
- E-Mail als Eigentum des Benutzers:
Wenn das Feld eine Eigenschaft des Benutzers ist, würde die Benutzerantwort ungefähr so aussehen:
Dies bedeutet, dass es keinen speziellen Endpunkt für E-Mails gibt. Sie können einen Benutzer jetzt anhand seiner E-Mail-Adresse finden, indem Sie die folgende Anfrage senden :
/[email protected]
. Welche (vorausgesetzt, E-Mails sind nur für Benutzer) eine Sammlung mit einem Benutzerelement zurückgeben, das mit der E-Mail übereinstimmt.- E-Mail als Ressource:
Aber wenn E-Mails von Benutzern auch Ressourcen sind. Anschließend können Sie eine API
/users/[user_id]/emails
erstellen, in der eine Sammlung von E-Mail-Adressen für Benutzer mit ID zurückgegeben wirduser_id
./users/[user_id]/emails/[email_id]
Gibt die E-Mail des Benutzers mit user_id und ['email_id'] zurück. Was Sie als Bezeichner verwenden, liegt bei Ihnen, aber ich würde mich an eine ganze Zahl halten. Sie können eine E-Mail vom Benutzer löschen, indem Sie eineDELETE
Anfrage an den Pfad senden , der die E-Mail identifiziert, die Sie löschen möchten. So löscht beispielsweiseDELETE
on/users/[user_id]/emails/[email_id]
die E-Mail mit email_id, die dem Benutzer mit user_id gehört. Höchstwahrscheinlich darf nur dieser Benutzer diesen Löschvorgang ausführen. Andere Benutzer erhalten eine 401-Antwort.Wenn ein Benutzer nur eine E-Mail-Adresse haben kann, können Sie sich daran halten.
/users/[user_id]/email
Dies gibt eine Singleton-Ressource zurück. Der Benutzer kann seine E-Mail-Adresse aktualisieren, indem erPUT
die E-Mail-Adresse unter dieser URL eingibt.quelle