Soll ich für REST-Ressourcen die Namenskonvention Singular oder Plural verwenden?

Question

Ich bin neu in REST und ich habe beobachtet, dass in einigen RESTful Dienste sie unterschiedliche Ressource URI für update/get/delete und Create verwenden. Wie zum Beispiel

• Erstellen - mit /Ressourcen mit POST-Methode (Plural beachten) an einigen Stellen mit /Ressource (Singular)
• Aktualisierung - mit /Ressourcen/123 mit PUT-Methode
• Holen - Verwenden /Ressourcen/123 mit GET-Methode

Ich bin ein wenig verwirrt über diese URI-Namenskonvention. Was sollten wir für die Erstellung von Ressourcen im Plural oder Singular verwenden? Was sollten die Kriterien sein, wenn ich das entscheide?

Answer 1

Für mich ist es besser, ein Schema zu haben, das man direkt auf den Code abbilden kann (leicht zu automatisieren), vor allem weil der Code das ist, was an beiden Enden sein wird.

GET  /orders          <---> orders 
POST /orders          <---> orders.push(data)
GET  /orders/1        <---> orders[1]
PUT  /orders/1        <---> orders[1] = data
GET  /orders/1/lines  <---> orders[1].lines
POST /orders/1/lines  <---> orders[1].lines.push(data)

Answer 2

Die Prämisse der Verwendung von /resources ist, dass sie "alle" Ressourcen darstellt. Wenn Sie eine GET /resources werden Sie wahrscheinlich die gesamte Sammlung zurückgeben. Durch POSTing an /resources fügen Sie der Sammlung hinzu.

Die einzelnen Ressourcen sind jedoch unter /resource verfügbar. Wenn Sie eine GET /resource werden Sie wahrscheinlich eine Fehlermeldung erhalten, da diese Anfrage keinen Sinn ergibt, während /resource/123 macht absolut Sinn.

使用方法 /resource anstelle von /resources ist vergleichbar mit der Vorgehensweise bei der Arbeit mit einem Dateisystem und einer Sammlung von Dateien und /resource ist das "Verzeichnis" mit den einzelnen 123 , 456 Dateien enthalten.

Weder das eine noch das andere ist richtig oder falsch, entscheiden Sie sich für das, was Ihnen am besten gefällt.

Answer 3

Ich sehe darin auch keinen Sinn, und ich denke, dass es nicht das beste URI-Design ist. Als Benutzer eines RESTful-Dienstes würde ich erwarten, dass die Listenressource denselben Namen hat, unabhängig davon, ob ich auf die Liste oder eine bestimmte Ressource "in" der Liste zugreife. Sie sollten die gleichen Bezeichner verwenden, unabhängig davon, ob Sie die Listenressource oder eine bestimmte Ressource verwenden wollen.

Answer 4

Plural

• Einfach - alle Urls beginnen mit demselben Präfix
• Logisch - orders/ erhält eine Indexliste der Aufträge.
• Standard - Der am weitesten verbreitete Standard, dem die überwiegende Mehrheit der öffentlichen und privaten APIs folgt.

Zum Beispiel:

GET /resources - gibt eine Liste von Ressourcenelementen zurück

POST /resources - erstellt ein oder mehrere Ressourcenobjekte

PUT /resources - aktualisiert ein oder mehrere Ressourcenelemente

PATCH /resources - aktualisiert teilweise eine oder mehrere Ressourcenpositionen

DELETE /resources - löscht alle Ressourcenelemente

Und für einzelne Ressourcenposten:

GET /resources/:id - gibt ein bestimmtes Ressourcenelement zurück, das auf :id Parameter

POST /resources/:id - erstellt ein Ressourcenelement mit der angegebenen ID (erfordert Validierung)

PUT /resources/:id - aktualisiert ein bestimmtes Ressourcenelement

PATCH /resources/:id - ein bestimmtes Ressourcenelement teilweise aktualisiert

DELETE /resources/:id - löscht ein bestimmtes Ressourcenelement

Für die Befürworter des Singulars: Sehen Sie es so: Würden Sie jemanden um eine order und erwarten eine Sache oder eine Liste von Dingen? Warum sollten Sie also von einem Dienst erwarten, dass er eine Liste von Dingen zurückgibt, wenn Sie eingeben /order ?

Answer 5

Einzigartig

Bequemlichkeit Dinge können unregelmäßige Pluralnamen haben. Manchmal haben sie keinen. Aber Singularnamen gibt es immer.

z. B. CustomerAddress über CustomerAddresses

Beachten Sie diese verwandte Ressource.

Este /order/12/orderdetail/12 ist besser lesbar und logischer als /orders/12/orderdetails/4 .

Datenbank-Tabellen

Eine Ressource stellt eine Entität wie eine Datenbanktabelle dar. Sie sollte einen logischen, eindeutigen Namen haben. Hier ist die Antwort über Tabellennamen.

Klasse Mapping

Klassen sind immer singulär. ORM-Tools erzeugen Tabellen mit denselben Namen wie die Klassen. Da immer mehr Tools verwendet werden, werden singuläre Namen zum Standard.

Lesen Sie mehr über Das Dilemma eines REST-API-Entwicklers

Für Dinge ohne Eigennamen

Im Fall von trousers y sunglasses Sie scheinen kein einzigartiges Gegenstück zu haben. Sie sind allgemein bekannt und scheinen durch ihre Verwendung Singular zu sein. Wie ein Paar Schuhe. Überlegen Sie sich einen Namen für die Klassendatei Shoe o Shoes . Hier müssen diese Namen durch ihre Verwendung als eine einzige Einheit betrachtet werden. Sie werden niemanden sehen, der einen einzelnen Schuh kauft, um die URL als

/shoe/23

Wir müssen sehen Shoes als singuläre Einheit.

Referenz: Die 6 besten Praktiken für die REST-Benennung