REST-URI-Konvention - Singular- oder Pluralname der Ressource beim Erstellen

Ich bin neu in REST und habe festgestellt, dass in einigen RESTful-Diensten unterschiedliche Ressourcen-URIs zum Aktualisieren / Abrufen / Löschen und Erstellen verwendet werden. Sowie

• Erstellen - Verwenden von / resources mit der POST-Methode (Plural beobachten) an einigen Stellen mit / resource (Singular)
• Update - mit / resource / 123 mit PUT-Methode
• Get - Using / resource / 123 mit der GET-Methode

Ich bin ein bisschen verwirrt über diese URI-Namenskonvention. Was sollten wir Plural oder Singular für die Ressourcenerstellung verwenden? Was sollten die Kriterien sein, um das zu entscheiden?

Die Voraussetzung für die Verwendung /resourcesist, dass sie "alle" Ressourcen darstellt. Wenn Sie a ausführen GET /resources, werden Sie wahrscheinlich die gesamte Sammlung zurückgeben. Durch POSTEN an fügen /resourcesSie der Sammlung etwas hinzu.

Die einzelnen Ressourcen sind jedoch unter / resource verfügbar. Wenn Sie a ausführen GET /resource, werden Sie wahrscheinlich einen Fehler machen, da diese Anfrage keinen Sinn ergibt, während dies /resource/123durchaus Sinn macht.

Unter Verwendung /resourceanstelle von /resourcesähnelt , wie Sie dies tun würden , wenn Sie mit, sagen wir gearbeitet haben, ein Dateisystem und eine Sammlung von Dateien und /resourceist das „Verzeichnis“ mit den einzelnen 123, 456Dateien darin.

Keiner der Wege ist richtig oder falsch, gehen Sie mit dem, was Ihnen am besten gefällt.

Für mich ist es besser, ein Schema zu haben, das Sie direkt dem Code zuordnen können (einfach zu automatisieren), hauptsächlich weil Code an beiden Enden vorhanden 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) 

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

Plural

• Einfach - alle URLs beginnen mit demselben Präfix
• Logisch - orders/Ruft eine Indexliste der Bestellungen ab.
• Standard - Am weitesten verbreiteter Standard, gefolgt von der überwiegenden Mehrheit der öffentlichen und privaten APIs.

Zum Beispiel:

GET /resources - gibt eine Liste der Ressourcenelemente zurück

POST /resources - Erstellt ein oder mehrere Ressourcenelemente

PUT /resources - Aktualisiert ein oder mehrere Ressourcenelemente

PATCH /resources - aktualisiert teilweise ein oder mehrere Ressourcenelemente

DELETE /resources - löscht alle Ressourcenelemente

Und für einzelne Ressourcenelemente:

GET /resources/:id- gibt ein bestimmtes Ressourcenelement basierend auf dem :idParameter zurück

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

PUT /resources/:id - Aktualisiert ein bestimmtes Ressourcenelement

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

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

Stellen Sie sich die Befürworter von Singular folgendermaßen vor: Würden Sie jemanden nach einem fragen orderund eine Sache oder eine Liste von Dingen erwarten? Warum sollten Sie also erwarten, dass ein Dienst beim Tippen eine Liste von Dingen zurückgibt /order?

Singular

Bequemlichkeit Dinge können unregelmäßige Pluralnamen haben. Manchmal haben sie keine. Aber Singularnamen sind immer da.

zB CustomerAddress über CustomerAddresses

Betrachten Sie diese verwandte Ressource.

Dies /order/12/orderdetail/12ist lesbarer und logischer als /orders/12/orderdetails/4.

Datenbanktabellen

Eine Ressource repräsentiert eine Entität wie eine Datenbanktabelle. Es sollte einen logischen Singularnamen haben. Hier ist die Antwort über Tabellennamen.

Klassenzuordnung

Klassen sind immer einzigartig. ORM-Tools generieren Tabellen mit denselben Namen wie Klassennamen. Da immer mehr Werkzeuge verwendet werden, werden einzelne Namen zum Standard.

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

Während die am weitesten verbreitete Praxis RESTful Apis sind, bei denen Pluralformen verwendet werden, z /api/resources/123 gibt es einen Sonderfall, in dem ich die Verwendung eines Singularnamens angemessener / ausdrucksvoller finde als Pluralnamen. Es ist der Fall von Eins-zu-Eins-Beziehungen. Insbesondere, wenn das Zielelement ein Wertobjekt ist (im domänengesteuerten Entwurfsparadigma).

Nehmen wir an, jede Ressource hat eine Eins-zu-Eins-Ressource, accessLogdie als Wertobjekt modelliert werden kann, dh keine Entität, daher keine ID. Es könnte ausgedrückt werden als /api/resources/123/accessLog. Die üblichen Verben (POST, PUT, DELETE, GET) würden die Absicht und auch die Tatsache, dass die Beziehung tatsächlich eins zu eins ist, angemessen ausdrücken.

Warum nicht dem vorherrschenden Trend der Namen von Datenbanktabellen folgen, bei denen eine singuläre Form allgemein akzeptiert wird? War schon da, hab das gemacht - lass uns wiederverwenden.

Tabellennamensdilemma: Singular vs. Plural Names

Ich bin überrascht zu sehen, dass so viele Menschen auf den Plural Nomen Bandwagon springen würden. Kümmern Sie sich bei der Implementierung von Konvertierungen von Singular in Plural um unregelmäßige Substantive im Plural? Magst du Schmerzen?

Siehe http://web2.uvcs.uvic.ca/elc/studyzone/330/grammar/irrplu.htm

Es gibt viele Arten von unregelmäßigem Plural, aber diese sind die häufigsten:

Nomen-Typ Bildung des Plural-Beispiels

Ends with -fe   Change f to v then Add -s   
    knife   knives 
    life   lives 
    wife   wives
Ends with -f    Change f to v then Add -es  
    half   halves 
    wolf   wolves
    loaf   loaves
Ends with -o    Add -es 
    potato   potatoes
    tomato   tomatoes
    volcano   volcanoes
Ends with -us   Change -us to -i    
    cactus   cacti
    nucleus   nuclei
    focus   foci
Ends with -is   Change -is to -es   
    analysis   analyses
    crisis   crises
    thesis   theses
Ends with -on   Change -on to -a    
    phenomenon   phenomena
    criterion   criteria
ALL KINDS   Change the vowel or Change the word or Add a different ending   
     man   men
     foot   feet
     child   children
     person   people
     tooth   teeth
     mouse   mice
 Unchanging Singular and plural are the same    
     sheep deer fish (sometimes)

Aus Sicht des API-Verbrauchers sollten die Endpunkte vorhersehbar sein

Im Idealfall...

1. GET /resources sollte eine Liste von Ressourcen zurückgeben.
2. GET /resource sollte einen Statuscode mit 400 Ebenen zurückgeben.
3. GET /resources/id/{resourceId} sollte eine Sammlung mit einer Ressource zurückgeben.
4. GET /resource/id/{resourceId} sollte ein Ressourcenobjekt zurückgeben.
5. POST /resources sollte Stapel Ressourcen erstellen.
6. POST /resource sollte eine Ressource erstellen.
7. PUT /resource sollte ein Ressourcenobjekt aktualisieren.
8. PATCH /resource sollte eine Ressource aktualisieren, indem nur die geänderten Attribute veröffentlicht werden.
9. PATCH /resources sollten Batch-Aktualisierungsressourcen nur die geänderten Attribute veröffentlichen.
10. DELETE /resourcessollte alle Ressourcen löschen; nur ein Scherz: 400 Statuscode
11. DELETE /resource/id/{resourceId}

Dieser Ansatz ist am flexibelsten und funktionsreichsten, aber auch am zeitaufwändigsten zu entwickeln. Wenn Sie es also eilig haben (was bei der Softwareentwicklung immer der Fall ist), nennen Sie einfach Ihren Endpunkt resourceoder die Pluralform resources. Ich bevorzuge die Singularform, weil Sie die Möglichkeit haben, programmgesteuert nach innen zu schauen und zu bewerten, da nicht alle Pluralformen mit 's' enden.

Abgesehen davon, aus welchem ​​Grund auch immer, haben sich die am häufigsten verwendeten Praxisentwickler für die Verwendung der Pluralform entschieden. Dies ist letztendlich die Route, die ich gewählt habe und wenn man sich beliebte Apis wie githubund ansiehttwitter , ist dies das, was sie tun.

Einige Kriterien für die Entscheidung könnten sein:

1. Was sind meine zeitlichen Einschränkungen?
2. Welche Operationen erlaube ich meinen Verbrauchern?
3. Wie sieht die Nutzlast für Anforderung und Ergebnis aus?
4. Möchte ich Reflection verwenden und den URI in meinem Code analysieren können?

Also liegt es an dir. Was auch immer Sie tun, seien Sie konsequent.

Meine zwei Cent: Methoden, die ihre Zeit damit verbringen, von Plural zu Singular oder umgekehrt zu wechseln, sind eine Verschwendung von CPU-Zyklen. Ich mag altmodisch sein, aber zu meiner Zeit wurden die Dinge gleich genannt. Wie suche ich nach Methoden für Menschen? Kein regelmäßiger Ausdruck deckt sowohl Personen als auch Personen ohne unerwünschte Nebenwirkungen ab.

Englische Pluralformen können sehr willkürlich sein und belasten den Code unnötig. Halten Sie sich an eine Namenskonvention. Bei Computersprachen sollte es um mathematische Klarheit gehen, nicht um die Nachahmung natürlicher Sprache.

Ich bevorzuge die Verwendung der Singularform sowohl für die Einfachheit als auch für die Konsistenz.

Zum Beispiel unter Berücksichtigung der folgenden URL:

/ Kunde / 1

Ich werde den Kunden als Kundensammlung behandeln, aber der Einfachheit halber wird der Sammlungsteil entfernt.

Ein anderes Beispiel:

/ Ausrüstung / 1

In diesem Fall haben Ausrüstungen nicht die richtige Pluralform. Wenn Sie es also als Ausrüstungssammlung behandeln und der Einfachheit halber entfernen, stimmt es mit dem Kundenfall überein.

Eine ID in einer Route sollte genauso angezeigt werden wie ein Index für eine Liste, und die Benennung sollte entsprechend erfolgen.

numbers = [1, 2, 3]

numbers            GET /numbers
numbers[1]         GET /numbers/1
numbers.push(4)    POST /numbers
numbers[1] = 23    UPDATE /numbers/1

Einige Ressourcen verwenden jedoch keine IDs in ihren Routen, da entweder nur eine vorhanden ist oder ein Benutzer nie Zugriff auf mehr als eine hat. Dies sind also keine Listen:

GET /dashboard
DELETE /session
POST /login
GET /users/{:id}/profile
UPDATE /users/{:id}/profile

Bei Namenskonventionen ist es normalerweise sicher zu sagen, dass Sie nur eine auswählen und dabei bleiben müssen, was Sinn macht.

Nachdem Sie REST vielen Personen erklären müssen, ist die Darstellung von Endpunkten als Pfade in einem Dateisystem die ausdrucksstärkste Methode.
Es ist zustandslos (Dateien existieren oder existieren nicht), hierarchisch, einfach und vertraut - Sie wissen bereits, wie Sie lokal oder über http auf statische Dateien zugreifen können.

In diesem Zusammenhang können sprachliche Regeln Sie nur bis zu folgenden Punkten führen:

Ein Verzeichnis kann mehrere Dateien und / oder Unterverzeichnisse enthalten und daher sein Name sollte in Pluralform sein.

Und ich mag es.
Auf der anderen Seite - es ist Ihr Verzeichnis, können Sie es "eine Ressource oder mehrere Ressourcen" nennen, wenn Sie dies möchten. Das ist nicht wirklich wichtig.

Wichtig ist, dass Sie /resourceS/123nicht erwarten können, dass Sie auf eine Datei mit dem Namen "123" in einem Verzeichnis mit dem Namen "resourceS" zugreifen können (was dazu führt ) /resource/123.

Versuchen Sie nicht, es intelligenter zu machen, als es sein muss - der Wechsel von Plural zu Singluar, abhängig von der Anzahl der Ressourcen, auf die Sie gerade zugreifen, mag für manche ästhetisch ansprechend sein, aber es ist nicht effektiv und macht in a keinen Sinn hierarchisch System.

Hinweis: Technisch gesehen können Sie "symbolische Links" /resources/123erstellen , so dass auch über zugegriffen werden kann /resource/123, aber erstere müssen noch vorhanden sein!

Schauen Sie sich das API-Designhandbuch von Google an : Ressourcennamen für ein anderes nehmen auf die Benennung Ressourcen.

Zusamenfassend:

• Sammlungen sind mit Pluralformen benannt.
• Einzelne Ressourcen werden mit einer Zeichenfolge benannt.

|--------------------------+---------------+-------------------+---------------+--------------|
| API Service Name         | Collection ID | Resource ID       | Collection ID | Resource ID  |
|--------------------------+---------------+-------------------+---------------+--------------|
| //mail.googleapis.com    | /users        | /[email protected] | /settings     | /customFrom  |
| //storage.googleapis.com | /buckets      | /bucket-id        | /objects      | /object-id   |
|--------------------------+---------------+-------------------+---------------+--------------|

Es lohnt sich zu lesen, wenn Sie über dieses Thema nachdenken.

Die Verwendung von Plural für alle Methoden ist zumindest in einem Aspekt praktischer: Wenn Sie eine Ressourcen-API mit Postman (oder einem ähnlichen Tool) entwickeln und testen, müssen Sie den URI nicht bearbeiten, wenn Sie von GET zu PUT zu POST usw. Wechseln .

Beide Darstellungen sind nützlich. Ich hatte Singular aus Bequemlichkeitsgründen für einige Zeit verwendet, Beugung kann schwierig sein. Aufgrund meiner Erfahrung bei der Entwicklung streng singulärer REST-APIs fehlt den Entwicklern, die den Endpunkt verwenden, die Gewissheit über die Form des Ergebnisses. Ich bevorzuge es jetzt, den Begriff zu verwenden, der die Form der Antwort am besten beschreibt.

Wenn alle Ihre Ressourcen auf höchstem Niveau sind, können Sie mit einzelnen Darstellungen davonkommen. Beugung zu vermeiden ist ein großer Gewinn.

Wenn Sie eine Art Deep Linking durchführen, um Abfragen zu Beziehungen darzustellen, können Entwickler, die gegen Ihre API schreiben, durch eine strengere Konvention unterstützt werden.

Meine Konvention ist, dass jede Tiefenebene in einem URI eine Interaktion mit der übergeordneten Ressource beschreibt und der vollständige URI implizit beschreiben sollte, was abgerufen wird.

Angenommen, wir haben das folgende Modell.

interface User {
    <string>id;
    <Friend[]>friends;
    <Manager>user;
}

interface Friend {
    <string>id;
    <User>user;
    ...<<friendship specific props>>
}

Wenn ich eine Ressource bereitstellen müsste, mit der ein Client den Manager eines bestimmten Freundes eines bestimmten Benutzers abrufen kann, könnte dies folgendermaßen aussehen:

GET /users/{id}/friends/{friendId}/manager

Im Folgenden sind einige weitere Beispiele aufgeführt:

• GET /users - Listen Sie die Benutzerressourcen in der globalen Benutzersammlung auf
• POST /users - Erstellen Sie einen neuen Benutzer in der globalen Benutzersammlung
• GET /users/{id} - einen bestimmten Benutzer aus der globalen Benutzersammlung abrufen
• GET /users/{id}/manager - Holen Sie sich den Manager eines bestimmten Benutzers
• GET /users/{id}/friends - Holen Sie sich die Liste der Freunde eines Benutzers
• GET /users/{id}/friends/{friendId} - einen bestimmten Freund eines Benutzers finden
• LINK /users/{id}/friends - Fügen Sie diesem Benutzer eine Freundesvereinigung hinzu
• UNLINK /users/{id}/friends - Entfernen Sie eine Freundesvereinigung von diesem Benutzer

Beachten Sie, wie jede Ebene einem übergeordneten Element zugeordnet wird, auf das reagiert werden kann. Die Verwendung verschiedener Eltern für dasselbe Objekt ist nicht intuitiv. Das Abrufen einer Ressource unter GET /resource/123lässt keinen Hinweis darauf, dass das Erstellen einer neuen Ressource unter erfolgen sollPOST /resources

Ich weiß, dass die meisten Menschen zwischen der Entscheidung, ob sie Plural oder Singular verwenden, stehen. Das Problem, das hier nicht angesprochen wurde, ist, dass der Client wissen muss, welches Sie verwenden, und dass er immer wahrscheinlich einen Fehler macht. Hier kommt mein Vorschlag her.

Wie wäre es mit beidem? Und damit meine ich, verwenden Sie Singular für Ihre gesamte API und erstellen Sie dann Routen, um Anforderungen im Plural an die Singularform weiterzuleiten. Zum Beispiel:

GET  /resources     =     GET  /resource
GET  /resources/1   =     GET  /resource/1
POST /resources/1   =     POST /resource/1
...

Du bekommst das Bild. Niemand ist falsch, minimaler Aufwand, und der Kunde wird es immer richtig machen.

Ich mag es nicht, wenn sich der {id}Teil der URLs mit Unterressourcen überschneidet, da iddies theoretisch alles sein könnte und es Unklarheiten geben würde. Es werden verschiedene Konzepte (Bezeichner und Unterressourcennamen) gemischt.

Ähnliche Probleme werden oft in zu sehen enumKonstanten oder Ordnerstrukturen, in denen unterschiedliche Konzepte gemischt sind (zum Beispiel, wenn Sie Ordner haben Tigers, Lionsund Cheetahs, und dann auch ein Ordner mit dem Namen Animalsauf dem gleichen Niveau - das macht keinen Sinn , da man eine Teilmenge die ist andere).

Im Allgemeinen denke ich, dass der zuletzt genannte Teil eines Endpunkts singulär sein sollte, wenn er sich jeweils mit einer einzelnen Entität befasst, und plural, wenn er sich mit einer Liste von Entitäten befasst.

Endpunkte, die sich mit einem einzelnen Benutzer befassen:

GET  /user             -> Not allowed, 400
GET  /user/{id}        -> Returns user with given id
POST /user             -> Creates a new user
PUT  /user/{id}        -> Updates user with given id
DELETE /user/{id}      -> Deletes user with given id

Dann gibt es eine separate Ressource für die Abfrage von Benutzern, die im Allgemeinen eine Liste zurückgeben:

GET /users             -> Lists all users, optionally filtered by way of parameters
GET /users/new?since=x -> Gets all users that are new since a specific time
GET /users/top?max=x   -> Gets top X active users

Und hier einige Beispiele für eine Unterressource, die sich mit einem bestimmten Benutzer befasst:

GET /user/{id}/friends -> Returns a list of friends of given user

Machen Sie einen Freund (viele zu viele Link):

PUT /user/{id}/friend/{id}     -> Befriends two users
DELETE /user/{id}/friend/{id}  -> Unfriends two users
GET /user/{id}/friend/{id}     -> Gets status of friendship between two users

Es gibt niemals Mehrdeutigkeiten, und die Plural- oder Singularbenennung der Ressource ist ein Hinweis für den Benutzer, was er erwarten kann (Liste oder Objekt). Es gibt keine Einschränkungen für ids, die es theoretisch ermöglichen, einen Benutzer mit der ID zu haben, newohne sich mit einem (potenziellen zukünftigen) Subressourcennamen zu überschneiden.

Verwenden Sie Singular und nutzen Sie die englische Konvention, z. B. "Business Directory".

Viele Dinge lesen sich so: "Bücherregal", "Hundepaket", "Kunstgalerie", "Filmfestival", "Autolot" usw.

Dies entspricht bequem dem URL-Pfad von links nach rechts. Artikeltyp links. Stellen Sie den Typ rechts ein.

Ruft GET /userswirklich jemals eine Gruppe von Benutzern ab? Nicht gewöhnlich. Es ruft eine Reihe von Stubs ab, die einen Schlüssel und möglicherweise einen Benutzernamen enthalten. Also ist es /userssowieso nicht wirklich . Es ist ein Benutzerindex oder ein "Benutzerindex", wenn Sie so wollen. Warum nennst du es nicht so? Es ist ein /user/index. Da wir den Set-Typ benannt haben, können wir mehrere Typen haben, die unterschiedliche Projektionen eines Benutzers anzeigen, ohne auf Abfrageparameter zurückgreifen zu müssen, z . B. user/phone-listoder /user/mailing-list.

Und was ist mit User 300? Es ist immer noch /user/300.

GET /user/index
GET /user/{id}

POST /user
PUT /user/{id}

DELETE /user/{id}

Abschließend kann HTTP immer nur eine einzige Antwort auf eine einzelne Anfrage haben. Ein Pfad bezieht sich immer auf ein singuläres Etwas.

Für mich manipulieren Pluralformen die Sammlung , während Singulars den Gegenstand in dieser Sammlung manipulieren .

Die Sammlung ermöglicht die Methoden GET / POST / DELETE

Item erlaubt die Methoden GET / PUT / DELETE

Zum Beispiel

POST on / Schüler fügen einen neuen Schüler in die Schule ein.

DELETE on / Schüler entfernen alle Schüler in der Schule.

DELETE on / student / 123 entfernt Schüler 123 aus der Schule.

Es mag sich unwichtig anfühlen, aber einige Ingenieure vergessen manchmal den Ausweis. Wenn die Route immer plural war und ein LÖSCHEN ausführte, könnten Sie Ihre Daten versehentlich löschen. Wenn die ID auf dem Singular fehlt, wird eine 404-Route zurückgegeben, die nicht gefunden wurde.

Um das Beispiel weiter zu erweitern, wenn die API mehrere Schulen verfügbar machen sollte, dann so etwas wie

DELETE on / school / abc / students entfernt alle Schüler in der Schule abc.

Das richtige Wort zu wählen ist manchmal eine Herausforderung für sich, aber ich möchte die Pluralität für die Sammlung beibehalten. ZB cart_itemsoder cart/itemsfühlt sich richtig an. Im Gegensatz zum Löschen cartwird das Warenkorbobjekt selbst gelöscht und nicht die Artikel im Warenkorb;).

Wie wäre es mit:

/resource/(nicht /resource)

/resource/ bedeutet, dass es sich um einen Ordner handelt, der als "Ressource" bezeichnet wird. Es handelt sich um einen "Ressourcen" -Ordner.

Und ich denke auch, dass die Namenskonvention von Datenbanktabellen dieselbe ist, zum Beispiel ist eine Tabelle namens "Benutzer" eine "Benutzertabelle", sie enthält etwas, das "Benutzer" genannt wird.

Ich bevorzuge die Verwendung von Plural ( /resources) und Singular ( /resource/{id}), da ich der Meinung bin, dass dies die Logik zwischen der Arbeit an der Sammlung von Ressourcen und der Arbeit an einer einzelnen Ressource klarer voneinander trennt.

Als wichtiger Nebeneffekt kann dies auch dazu beitragen, zu verhindern, dass jemand die API falsch verwendet. Stellen Sie sich beispielsweise den Fall vor, in dem ein Benutzer fälschlicherweise versucht, eine Ressource abzurufen, indem er die ID als folgenden Parameter angibt:

GET /resources?Id=123

In diesem Fall, wenn wir die Pluralversion verwenden, ignoriert der Server höchstwahrscheinlich den Parameter Id und gibt die Liste aller Ressourcen zurück. Wenn der Benutzer nicht aufpasst, glaubt er, dass der Anruf erfolgreich war, und verwendet die erste Ressource in der Liste.

Auf der anderen Seite, wenn Sie die Singularform verwenden:

GET /resource?Id=123

Der Server gibt höchstwahrscheinlich einen Fehler zurück, da die ID nicht richtig angegeben ist und der Benutzer feststellen muss, dass etwas nicht stimmt.