REST-API-DESIGN - Abrufen einer Ressource über REST mit unterschiedlichen Parametern, aber demselben URL-Muster

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!

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 bereitgestellten idoder nicht existiert email. Ich wäre auch nicht überrascht zu sehen GET /users/id/{id}(obwohl es meiner Meinung nach überflüssig ist).

Kommentare zu den anderen Ansätzen

1. GET /users/id={id} GET /users/email={email}
   • Ich glaube nicht, dass ich das gesehen habe, und wenn ich es gesehen hätte, wäre es sehr verwirrend. Es ist fast so, als würde versucht, Abfrageparameter mit Pfadparametern zu imitieren.
2. GET /users?id={id} GET /users?email={email}
   • Ich denke, Sie haben den Nagel auf den Kopf getroffen, als Sie die Verwendung von Abfrageparametern zum Filtern erwähnt haben.
   • Wäre es jemals sinnvoll, diese Ressource sowohl mit einem idals auch mit einem email(z. B. GET /users?id={id}&email={email}) aufzurufen ? Wenn nicht, würde ich keine einzige Ressourcenmethode wie diese verwenden.
   • Ich würde erwarten, dass diese Methode zum Abrufen einer Liste von Benutzern mit optionalen Abfrageparametern zum Filtern verwendet wird, aber ich würde nicht erwarten id, emaildass eine eindeutige Kennung zu den Parametern gehört. Beispiel: GET /users?status=BANNEDGibt möglicherweise eine Liste der gesperrten Benutzer zurück.

_{Überprüfen Sie diese Antwort von einer verwandten Frage.}

Wenn Sie dies pragmatisch betrachten, haben Sie eine Sammlung von Benutzern:

/users   # this returns many

Jeder Benutzer hat einen dedizierten Ressourcenstandort:

/users/{id}    # this returns one

Sie haben auch eine Reihe von Möglichkeiten, nach Benutzern zu suchen:

/users?email={email}
/users?name=*bob*

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

Informationen zu den Benutzerressourcen

Auf dem Pfad erhalten /usersSie immer eine Sammlung von zurückgegebenen Benutzerressourcen.

Auf dem Weg können /users/[user_id]Sie verschiedene Dinge erwarten:

1. Sie sollten eine Singleton-Ressource erhalten, die die Benutzerressource mit ihrer Kennung [user_id] oder darstellt
2. Eine 404- Antwort wurde nicht gefunden, wenn kein Benutzer mit der ID [Benutzer-ID] vorhanden ist oder
3. ein verbotenes 401, wenn Sie nicht auf die angeforderte Benutzerressource zugreifen dürfen.

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 /usersmit Abfrageparametern ( GETParametern) 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:

{ 
  id: 1,
  firstName: 'John'
  lastName: 'Doe'
  email: 'john.doe@example.com'
  ...
}

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 : /users?email=john.doe@example.com. 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]/emailserstellen, in der eine Sammlung von E-Mail-Adressen für Benutzer mit ID zurückgegeben wird user_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 eine DELETEAnfrage an den Pfad senden , der die E-Mail identifiziert, die Sie löschen möchten. So löscht beispielsweise DELETEon /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 er PUTdie E-Mail-Adresse unter dieser URL eingibt.