Ist es sinnvoll, dass REST-Ressourcen Singular und Plural sind?

Ich habe mich gefragt, ob und nicht ein traditionelleres Layout wie dieses:

api/Products
GET // gets product(s) by id
PUT // updates product(s) by id
DELETE // deletes (product(s) by id
POST // creates product(s)

Wäre es sinnvoller, einen Singular und einen Plural zu haben, zum Beispiel:

api/Product
GET // gets a product by id
PUT // updates a product by id
DELETE // deletes a product by id
POST // creates a product

api/Products
GET // gets a collection of products by id
PUT // updates a collection of products by id
DELETE // deletes a collection of products (not the products themselves)
POST // creates a collection of products based on filter parameters passed

So erstellen Sie eine Sammlung von Produkten:

POST api/Products {data: filters} // returns api/Products/<id>

Und dann, um darauf zu verweisen, könnten Sie Folgendes tun:

GET api/Products/<id> // returns array of products

Meiner Meinung nach besteht der Hauptvorteil dieser Vorgehensweise darin, dass Produktkollektionen einfach zwischengespeichert werden können. Man könnte zum Beispiel eine Lebensdauer von einer Stunde für Produktkollektionen festlegen, wodurch die Anrufe auf einem Server drastisch reduziert werden. Natürlich sehe ich derzeit nur die gute Seite der Dinge auf diese Weise. Was ist der Nachteil?

rest Eva
quelle

Antworten:

Wenn eine Sammlung die nützlichste Art der Interaktion mit Ihrer API ist, kann es oft einfacher sein, sich eine einzelne Sammlung als Sammlung mit nur einem Mitglied vorzustellen. Wenn Sie später eine API für die Interaktion mit Singles verfügbar machen möchten, muss sie lediglich die mit diesem Mitglied übergebene Single in eine Sammlung konvertieren und verwendet dann die identische Implementierung der anderen API.

Ich denke, was ich hier sage, ist, wenn Sie möchten, dass Sammlungen ein Interaktionsmechanismus sind, beginnen Sie mit der API nur für Sammlungen, und nachdem das System abgeschlossen ist, ist die andere API eine einfache zusätzliche Zuordnung auf der Schnittstellenebene, die Sie dann hinzufügen können, wenn Sie finden es besonders nützlich. Möglicherweise ist die Nützlichkeit jedoch minimal genug, um YAGNI anzuwenden, und verwenden Sie einfach die Sammlungsoberfläche für die wenigen gewünschten Instanzen von Singles.

Jimmy Hoffa
quelle

Ich stimme Ihrer Meinung zu, wenn wir davon ausgehen, dass wir das obige Beispiel verwenden, da POST-API / -Produkte zum Übergeben von Sammlungsfilterparametern und nicht von Daten zum Erstellen neuer Produkte verwendet werden. Was wäre ein vernünftiger Weg, um ein neues Produkt zu erstellen? ohne API / Produkt?

Eva

@Evan Warum kann nicht auf API / Produkte gepostet werden, um mehrere (oder eine Sammlung von einem) Produkte einzufügen? Das erscheint mir am logischsten. Poste vielleicht Produkte / Filter zum Erstellen von Filtern oder erhalte, wenn es sich um eine Abruf- und keine Erstellungsaufgabe handelt.

Jimmy Hoffa

Danke für die Ausarbeitung, Jimmy. Der Grund, warum ich das nicht so sah, war, dass ich im obigen Beispiel die Sammlung als identifizierte Ressource an und für sich betrachtete. In einem Backend könnte api / Product "Product" und api / Products "ProductCollection" sein. Nach einiger Überlegung denke ich jedoch, dass es vielleicht besser ist, zu abstrahieren, dass alles weg von der API, wie in Ihrem Vorschlag ... nun zur eigentlichen Frage, sind Sie auf Ihrem Weg nach Thailand von diesem Truckstop weggefahren oder gegangen im Kofferraum eines Autos?

Eva

@Evan Ich gebe dir zwei Hinweise: Möwen.

Jimmy Hoffa

Der Nachteil ist, dass das aufrufende Programm auch den Ressourcennamen pluralisieren muss, was für Client-Sprachen, die keine integrierten Pluralisierungsmechanismen haben, schwierig sein kann. Wenn Sie es singulär lassen, ist es für den Anrufer einfacher, die Codegenerierung für seine Client-Bibliothek zu automatisieren.

Wenn Sie dies abmildern möchten, können Sie die SDKs für Ihren REST-Service selbst generieren. Oder Sie können einfach eine Meinung haben und sich mit der Beschwerde befassen :)

Chris McCall
quelle