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

Eine ID in einer Route ist wie ein Index in einer Liste zu betrachten, 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    PUT /numbers/1

Aber einige Ressourcen verwenden keine IDs in ihren Routen, weil es entweder nur eine gibt oder ein Benutzer nie Zugang zu mehr als einer hat, also sind das keine Listen:

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

Answer 2

Das Wichtigste

Jedes Mal, wenn Sie Pluralformen in Schnittstellen und Code verwenden, fragen Sie sich, wie Ihre Konvention mit solchen Wörtern umgeht:

• /pants , /eye-glasses - Ist das der Singular oder der Plural des Weges?

• /radii - Wissen Sie aus dem Stegreif, ob der singuläre Pfad dafür ist /radius o /radix ?

• /index - Wissen Sie aus dem Stegreif, ob es dafür einen pluralen Pfad gibt? /indexes o /indeces o /indices ?

Die Konventionen sollten idealerweise ohne Unregelmäßigkeiten skaliert werden. Bei den englischen Pluralen ist dies nicht der Fall, denn

1. es gibt Ausnahmen, z. B. wenn etwas in der Pluralform genannt wird, und
2. Es gibt keinen trivialen Algorithmus, um den Plural eines Wortes aus dem Singular zu ermitteln, den Singular aus dem Plural zu ermitteln oder festzustellen, ob ein unbekanntes Substantiv Singular oder Plural ist.

Das hat auch Nachteile. Die auffälligsten sind, wenn ich mich recht erinnere:

1. Die Substantive, deren Singular- und Pluralform identisch sind, zwingen Ihren Code dazu, den Fall zu behandeln, dass der "Plural"-Endpunkt und der "Singular"-Endpunkt ohnehin denselben Pfad haben.
2. Ihre Benutzer/Entwickler müssen die englische Sprache so gut beherrschen, dass sie die korrekte Einzahl und Mehrzahl von Substantiven kennen. In einer zunehmend internationalisierten Welt kann dies zu nicht zu vernachlässigendem Frust und Arbeitsaufwand führen.
3. Es verwandelt "Ich weiß" im Alleingang /foo/{{id}} was ist der Weg, um alles zu bekommen foo ?" in ein natürliches Sprachproblem zu verwandeln, statt in ein Problem, bei dem man den letzten Teil des Pfades einfach weglassen muss.

In einigen menschlichen Sprachen gibt es nicht einmal unterschiedliche Singular- und Pluralformen für Substantive. Sie kommen damit sehr gut zurecht. Das kann Ihre API auch.

Answer 3

Meine Meinung: Methoden, die ihre Zeit damit verbringen, vom Plural in den Singular oder umgekehrt zu wechseln, sind eine Verschwendung von CPU-Zyklen. Ich bin vielleicht altmodisch, aber zu meiner Zeit hießen solche Dinge noch gleich. Wie kann ich Methoden für Personen nachschlagen? Es gibt keinen regulären Ausdruck, der sowohl Person als auch Personen ohne unerwünschte Nebenwirkungen abdeckt.

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

Answer 4

Ich bevorzuge die Singularform, weil sie einfach und konsistent ist.

Betrachten Sie zum Beispiel die folgende Url:

/Kunde/1

Ich werde den Kunden als Kundenerfassung behandeln, aber der Einfachheit halber wird der Erfassungsteil entfernt.

Ein weiteres Beispiel:

/Ausstattung/1

In diesem Fall ist Ausrüstungen nicht die richtige Pluralform. Die Behandlung als Gerätesammlung und das Entfernen der Sammlung der Einfachheit halber stimmt mit dem Kundenfall überein.

Answer 5

Hier ist Roy Fieldings Dissertation von " Architekturstile und der Entwurf netzgestützter Softwarearchitekturen ", und dieses Zitat könnte Sie interessieren:

Eine Ressource ist eine konzeptionelle Abbildung auf eine Reihe von Entitäten, nicht die Entität, die der Abbildung zu einem bestimmten Zeitpunkt entspricht Zeitpunkt entspricht.

Da es sich um eine Ressource, eine Zuordnung zu einer Reihe von Entitäten handelt, erscheint es mir nicht logisch, die /product/ als Ressource für den Zugriff auf eine Reihe von Produkten, anstatt /products/ selbst. Und wenn Sie ein bestimmtes Produkt benötigen, dann greifen Sie /products/1/ .

Als weitere Referenz finden Sie in dieser Quelle einige Wörter und Beispiele zu den Namenskonventionen für Ressourcen:

• https://restfulapi.net/resource-naming/