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

Warum folgt man nicht dem vorherrschenden Trend bei den Namen von Datenbanktabellen, bei denen sich eine Singularform durchgesetzt hat? Gesagt, getan - verwenden wir sie wieder.

Dilemma bei der Benennung von Tabellen: Singular- und Plural-Namen

Answer 2

Siehe Googles API-Design-Leitfaden: Ressourcennamen für einen anderen Ansatz zur Benennung von Ressourcen.

Der Leitfaden schreibt vor, dass Sammlungen mit Plural benannt werden müssen.

|--------------------------+---------------+-------------------+---------------+--------------|
| API Service Name         | Collection ID | Resource ID       | Collection ID | Resource ID  |
|--------------------------+---------------+-------------------+---------------+--------------|
| //mail.googleapis.com    | /users        | /name@example.com | /settings     | /customFrom  |
| //storage.googleapis.com | /buckets      | /bucket-id        | /objects      | /object-id   |
|--------------------------+---------------+-------------------+---------------+--------------|

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

Answer 3

Die am weitesten verbreitete Praxis sind RESTful Apis, bei denen Pluralformen verwendet werden, z. B. /api/resources/123 Es gibt einen besonderen Fall, in dem ich die Verwendung eines Einzahlnamens angemessener/aussagekräftiger finde als Pluralnamen. Es handelt sich um den Fall von Eins-zu-Eins-Beziehungen. Insbesondere, wenn das Zielobjekt ein Wertobjekt ist (im Paradigma des bereichsorientierten Designs).

Gehen wir davon aus, dass jede Ressource eine Eins-zu-eins accessLog das als Wertobjekt modelliert werden könnte, d. h. keine Entität und 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 zum Ausdruck bringen.

Answer 4

Ich bin überrascht, dass so viele Leute auf den Zug der Pluralnomen aufspringen. Kümmern Sie sich bei der Umwandlung von Singular in Plural um unregelmäßige Pluralnomen? Haben Sie Freude am Schmerz?

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

Es gibt viele Arten des unregelmäßigen Plurals, aber diese sind die häufigsten:

Substantivtyp Bildung des Plurals Beispiel

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)

Answer 5

Aus der Sicht des API-Kunden sollten die Endpunkte vorhersehbar sein, damit

Idealerweise...

1. GET /resources sollte eine Liste von Ressourcen zurückgeben.
2. GET /resource sollte einen Statuscode der Stufe 400 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 Ressourcen im Stapelverfahren 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 gebucht werden.
9. PATCH /resources sollte eine Stapelaktualisierung von Ressourcen vornehmen, die nur die geänderten Attribute verbucht.
10. DELETE /resources sollte alle Ressourcen löschen; nur ein Scherz: 400 status code
11. DELETE /resource/id/{resourceId}

Dieser Ansatz ist der flexibelste und funktionsreichste, aber auch der zeitaufwändigste in der Entwicklung. Wenn Sie es also eilig haben (was bei der Softwareentwicklung immer der Fall ist), nennen Sie Ihren Endpunkt einfach resource oder die Pluralform resources . Ich bevorzuge die Singularform, weil sie Ihnen die Möglichkeit gibt, sich selbst zu untersuchen und programmatisch zu bewerten, da nicht alle Pluralformen auf "s" enden.

Aus welchen Gründen auch immer haben sich die Entwickler für die Verwendung der Pluralform entschieden, die am weitesten verbreitet ist. Dies ist letztendlich der Weg, den ich gewählt habe, und wenn Sie sich beliebte Apis wie github y twitter Dies ist ihre Aufgabe.

Einige Entscheidungskriterien könnten sein:

1. Welche Zeitvorgaben habe ich?
2. Welche Operationen werde ich meinen Verbrauchern erlauben?
3. Wie sieht die Nutzlast von Anfrage und Ergebnis aus?
4. Möchte ich in der Lage sein, Reflection zu verwenden und den URI in meinem Code zu analysieren?

Es liegt also an Ihnen. Was immer Sie tun, seien Sie konsequent.