Convenzione REST URI - Nome singolare o plurale della risorsa durante la sua creazione

Sono nuovo di REST e ho notato che in alcuni servizi RESTful usano URI di risorse diverse per aggiornare / ottenere / cancellare e creare. Ad esempio

• Crea - usando / risorse con il metodo POST (osservare il plurale) in alcuni punti usando / risorsa (singolare)
• Aggiornamento - usando / resource / 123 con il metodo PUT
• Ottieni - Utilizzo di / resource / 123 con il metodo GET

Sono un po 'confuso su questa convenzione di denominazione dell'URI. Cosa dovremmo usare singolare o plurale per la creazione di risorse? Quali dovrebbero essere i criteri nel decidere ciò?

La premessa dell'utilizzo /resourcesè che rappresenta "tutte" le risorse. Se lo fai GET /resources, probabilmente restituirai l'intera collezione. POSTANDO a /resources, stai aggiungendo alla raccolta.

Tuttavia, le singole risorse sono disponibili su / resource. Se lo fai GET /resource, probabilmente sbaglierai, poiché questa richiesta non ha alcun senso, mentre /resource/123ha perfettamente senso.

Utilizzando /resourceinvece di /resourcesè simile a come si farebbe questo se si stesse lavorando con, diciamo, un file system e una raccolta di file e /resourceè la "cartella" con i singoli 123, 456file in essa contenuti.

In nessun modo è giusto o sbagliato, scegli quello che ti piace di più.

Per me è meglio avere uno schema che puoi mappare direttamente al codice (facile da automatizzare), principalmente perché il codice è quello che sarà ad entrambe le estremità.

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) 

Non vedo nemmeno il punto di fare questo e penso che non sia il miglior design URI. Come utente di un servizio RESTful, mi aspetto che la risorsa dell'elenco abbia lo stesso nome, indipendentemente dal fatto che acceda all'elenco o alla risorsa specifica "nell'elenco". È necessario utilizzare gli stessi identificatori, indipendentemente dal fatto che si desideri utilizzare la risorsa elenco o una risorsa specifica.

Plurale

• Semplice : tutti gli URL iniziano con lo stesso prefisso
• Logico -orders/ ottiene un elenco indice di ordini.
• Standard : lo standard più ampiamente adottato, seguito dalla stragrande maggioranza delle API pubbliche e private.

Per esempio:

GET /resources - restituisce un elenco di elementi delle risorse

POST /resources - crea uno o più elementi di risorse

PUT /resources - aggiorna uno o più elementi delle risorse

PATCH /resources - aggiorna parzialmente uno o più elementi di risorse

DELETE /resources - elimina tutti gli elementi delle risorse

E per gli elementi a risorsa singola:

GET /resources/:id- restituisce un elemento risorsa specifico in base al :idparametro

POST /resources/:id - crea un elemento di risorsa con ID specificato (richiede la convalida)

PUT /resources/:id - aggiorna un elemento di risorsa specifico

PATCH /resources/:id - aggiorna parzialmente un elemento di risorsa specifico

DELETE /resources/:id - elimina un elemento risorsa specifico

Ai sostenitori del singolare, la pensi in questo modo: chiederesti a qualcuno ordere ti aspetti una cosa o un elenco di cose? Quindi perché dovresti aspettarti che un servizio restituisca un elenco di cose quando digiti /order?

Singolare

Convenienza Le cose possono avere nomi plurali irregolari. A volte non ne hanno uno. Ma i nomi singolari sono sempre lì.

ad es. CustomerAddress su CustomerAddresses

Considera questa risorsa correlata.

Questo /order/12/orderdetail/12è più leggibile e logico di/orders/12/orderdetails/4 .

Tabelle database

Una risorsa rappresenta un'entità come una tabella di database. Dovrebbe avere un nome logico singolare. Ecco la risposta sui nomi delle tabelle.

Mappatura delle classi

Le lezioni sono sempre singolari. Gli strumenti ORM generano tabelle con gli stessi nomi dei nomi di classe. Man mano che vengono utilizzati sempre più strumenti, i nomi singolari stanno diventando uno standard.

Ulteriori informazioni sul dilemma dello sviluppatore di un'API REST

Mentre la pratica più diffusa sono le API RESTful in cui si usano i plurali /api/resources/123, ad esempio , c'è un caso speciale in cui trovo l'uso di un nome singolare più appropriato / espressivo dei nomi plurali. È il caso delle relazioni individuali. In particolare se l'elemento di destinazione è un oggetto valore (nel paradigma del design guidato dal dominio).

Supponiamo che ogni risorsa abbia uno-a-uno accessLogche potrebbe essere modellato come un oggetto valore, cioè non un'entità, quindi nessun ID. Potrebbe essere espresso come /api/resources/123/accessLog. I soliti verbi (POST, PUT, DELETE, GET) esprimono in modo appropriato l'intento e anche il fatto che la relazione sia davvero uno a uno.

Perché non seguire la tendenza prevalente dei nomi delle tabelle del database, in cui una forma singolare è generalmente accettata? Ci sono stato, fatto questo - riutilizziamo.

Dilemma di denominazione delle tabelle: nomi singolari e plurali

Sono sorpreso di vedere che così tante persone salterebbero sul carro del sostantivo plurale. Durante l'implementazione di conversioni dal singolare al plurale, ti occupi dei nomi plurali irregolari? Ti piace il dolore?

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

Esistono molti tipi di plurale irregolare, ma questi sono i più comuni:

Tipo di nome Formazione del plurale Esempio

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)

Dal punto di vista del consumatore API, gli endpoint dovrebbero essere prevedibili

Idealmente...

1. GET /resources dovrebbe restituire un elenco di risorse.
2. GET /resource dovrebbe restituire un codice di stato di livello 400.
3. GET /resources/id/{resourceId} dovrebbe restituire una raccolta con una risorsa.
4. GET /resource/id/{resourceId} dovrebbe restituire un oggetto risorsa.
5. POST /resources dovrebbe creare in batch risorse.
6. POST /resource dovrebbe creare una risorsa.
7. PUT /resource dovrebbe aggiornare un oggetto risorsa.
8. PATCH /resource dovrebbe aggiornare una risorsa pubblicando solo gli attributi modificati.
9. PATCH /resources dovrebbe aggiornare in batch le risorse pubblicando solo gli attributi modificati.
10. DELETE /resourcesdovrebbe eliminare tutte le risorse; sto scherzando: 400 codice di stato
11. DELETE /resource/id/{resourceId}

Questo approccio è il più flessibile e ricco di funzionalità, ma anche il più dispendioso in termini di tempo per lo sviluppo. Quindi, se hai fretta (che è sempre il caso dello sviluppo del software), dai un nome al tuo endpoint resourceo alla forma plurale resources. Preferisco la forma singolare perché ti dà la possibilità di introspettare e valutare programmaticamente poiché non tutte le forme plurali terminano in 's'.

Detto questo, per qualsiasi motivo lo sviluppatore della pratica più comunemente usato abbia scelto è usare la forma plurale. Questo è in definitiva il percorso che ho scelto e se guardi le apis popolari come githube twitter, questo è quello che fanno.

Alcuni criteri per decidere potrebbero essere:

1. Quali sono i miei vincoli temporali?
2. Quali operazioni consentirò ai miei consumatori di fare?
3. Che aspetto hanno il payload di richiesta e risultato?
4. Voglio essere in grado di utilizzare reflection e analizzare l'URI nel mio codice?

Quindi dipende da te. Tutto ciò che fai è coerente.

I miei due centesimi: i metodi che passano il loro tempo cambiando dal plurale al singolare o viceversa sono una perdita di cicli della CPU. Potrei essere di vecchia scuola, ma ai miei tempi come se le cose fossero chiamate uguali. Come posso cercare metodi riguardanti le persone? Nessuna espressione regolare coprirà sia la persona che le persone senza effetti collaterali indesiderati.

I plurali inglesi possono essere molto arbitrari e ingombrano inutilmente il codice. Attenersi a una convenzione di denominazione. I linguaggi del computer dovevano riguardare la chiarezza matematica, non la mimica del linguaggio naturale.

Preferisco usare la forma singolare sia per semplicità che per coerenza.

Ad esempio, considerando il seguente URL:

/ Cliente / 1

Tratterò il cliente come raccolta del cliente, ma per semplicità, la parte della raccolta viene rimossa.

Un altro esempio:

/ Attrezzature / 1

In questo caso, le apparecchiature non sono la forma plurale corretta. Quindi trattarlo come una raccolta di attrezzature e rimuovere la raccolta per semplicità lo rende coerente con il caso del cliente.

Un id in una route dovrebbe essere visualizzato come un indice di un elenco e la denominazione dovrebbe procedere di conseguenza.

numbers = [1, 2, 3]

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

Ma alcune risorse non usano gli ID nei loro percorsi perché ce n'è solo uno o un utente non ha mai accesso a più di uno, quindi quelli non sono elenchi:

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

Con le convenzioni di denominazione, di solito è sicuro dire "basta sceglierne uno e attenersi ad esso", il che ha senso.

Tuttavia, dopo aver dovuto spiegare REST a molte persone, rappresentare gli endpoint come percorsi su un file system è il modo più espressivo per farlo.
È apolide (i file esistono o non esistono), gerarchico, semplice e familiare: sai già come accedere ai file statici, localmente o via http.

E in quel contesto, le regole linguistiche possono arrivare solo a quanto segue:

Una directory può contenere più file e / o sottodirectory, pertanto il suo nome deve essere in forma plurale.

E questo mi piace.
Anche se, d'altra parte, è la tua directory, puoi chiamarla "a-resource-or-multiple-resources" se è quello che vuoi. Questa non è davvero la cosa importante.

Ciò che è importante è che se si inserisce un file denominato "123" in una directory denominata "risorse" (risultante /resourceS/123), non è possibile aspettarsi che sia accessibile tramite /resource/123.

Non cercare di renderlo più intelligente di quanto deve essere: passare da plurale a singolare a seconda del numero di risorse a cui stai attualmente accedendo potrebbe essere esteticamente piacevole per alcuni, ma non è efficace e non ha senso in un sistema gerarchico .

Nota: tecnicamente, puoi creare "collegamenti simbolici", in modo che sia /resources/123possibile accedervi anche tramite /resource/123, ma il primo deve ancora esistere!

Date un'occhiata a Google 's API Design Guide: Nomi risorse per prendere un altro sulle risorse di denominazione.

In breve:

• Le collezioni sono chiamate con plurali.
• Le singole risorse sono denominate con una stringa.

|--------------------------+---------------+-------------------+---------------+--------------|
| 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   |
|--------------------------+---------------+-------------------+---------------+--------------|

Vale la pena leggere se stai pensando a questo argomento.

L'uso del plurale per tutti i metodi è più pratico almeno in un aspetto: se stai sviluppando e testando un'API di risorse usando Postman (o uno strumento simile), non è necessario modificare l'URI quando passi da GET a PUT a POST ecc. .

Entrambe le rappresentazioni sono utili. Ho usato singolare per comodità per un po 'di tempo, l'inflessione può essere difficile. La mia esperienza nello sviluppo di API REST rigorosamente singolari, gli sviluppatori che consumano l'endpoint mancano di certezza su quale possa essere la forma del risultato. Ora preferisco usare il termine che meglio descrive la forma della risposta.

Se tutte le tue risorse sono di alto livello, puoi cavartela con rappresentazioni singolari. Evitare l'inflessione è una grande vittoria.

Se stai facendo qualsiasi tipo di deep linking per rappresentare query sulle relazioni, gli sviluppatori che scrivono contro la tua API possono essere aiutati da una convenzione più rigorosa.

La mia convenzione è che ogni livello di profondità in un URI sta descrivendo un'interazione con la risorsa padre e l'URI completo dovrebbe implicitamente descrivere ciò che viene recuperato.

Supponiamo di avere il seguente modello.

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

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

Se avessi bisogno di fornire una risorsa che consenta a un cliente di ottenere il gestore di un determinato amico di un determinato utente, potrebbe assomigliare a:

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

Di seguito sono riportati alcuni altri esempi:

• GET /users - elenca le risorse utente nella raccolta utenti globale
• POST /users - crea un nuovo utente nella raccolta di utenti globali
• GET /users/{id} - recuperare un utente specifico dalla raccolta di utenti globali
• GET /users/{id}/manager - ottenere il gestore di un utente specifico
• GET /users/{id}/friends - Ottieni l'elenco degli amici di un utente
• GET /users/{id}/friends/{friendId} - ottenere un amico specifico di un utente
• LINK /users/{id}/friends - aggiungi un'associazione di amici a questo utente
• UNLINK /users/{id}/friends - rimuovere un'associazione di amici da questo utente

Notare come ogni livello è associato a un genitore su cui può essere agito. L'uso di genitori diversi per lo stesso oggetto è controintuitivo. Il recupero di una risorsa in GET /resource/123non lascia alcuna indicazione sul fatto che la creazione di una nuova risorsa debba essere effettuata inPOST /resources

So che la maggior parte delle persone sta decidendo se usare il plurale o il singolare. Il problema che non è stato risolto qui è che il cliente dovrà sapere quale si sta utilizzando e è sempre probabile che commetta un errore. Ecco da dove viene il mio suggerimento.

Che ne dici di entrambi? E con ciò intendo usare singolare per l'intera API e quindi creare percorsi per inoltrare le richieste fatte in forma plurale alla forma singolare. Per esempio:

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

Ottieni l'immagine. Nessuno ha torto, il minimo sforzo e il cliente lo farà sempre bene.

Non mi piace vedere la {id}parte degli URL che si sovrappone alle risorse secondarie, dal momento idche teoricamente potrebbe esserci qualsiasi cosa e ci sarebbe ambiguità. Sta mescolando concetti diversi (identificatori e nomi delle risorse secondarie).

Problemi simili sono spesso visto in enumcostanti o una cartella di strutture, dove i diversi concetti sono misti (ad esempio, quando si dispone di cartelle Tigers, Lionse Cheetahs, e poi anche una cartella denominata Animalsallo stesso livello - questo non ha senso, come uno è un sottoinsieme della altro).

In generale, penso che l'ultima parte nominata di un endpoint dovrebbe essere singolare se si tratta di una singola entità alla volta, e plurale se si tratta di un elenco di entità.

Quindi endpoint che riguardano un singolo utente:

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

Quindi esiste una risorsa separata per eseguire query sugli utenti, che generalmente restituiscono un elenco:

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

E qui alcuni esempi di una sotto-risorsa che si occupa di un utente specifico:

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

Fai amicizia (link da molti a molti):

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

Non c'è mai alcuna ambiguità e la denominazione plurale o singolare della risorsa è un suggerimento per l'utente cosa possono aspettarsi (elenco o oggetto). Non ci sono restrizioni su ids, teoricamente rendendo possibile avere un utente con l'id newsenza sovrapposizioni con un nome (potenziale futuro) della sotto-risorsa.

Usa Singular e approfitta della convenzione inglese che si vede ad esempio in "Elenco società".

Molte cose leggono in questo modo: "Book Case", "Dog Pack", "Art Gallery", "Film Festival", "Car Lot", ecc.

Ciò corrisponde comodamente al percorso dell'URL da sinistra a destra. Tipo di oggetto a sinistra. Imposta il tipo a destra.

Recupera GET /usersmai davvero un insieme di utenti? Non solitamente. Recupera un set di matrici che contengono una chiave e forse un nome utente. Quindi non lo è davvero /users. È un indice di utenti, o un "indice di utenti", se vuoi. Perché non chiamarlo così? È un /user/index. Dato che abbiamo chiamato il tipo di set, possiamo avere più tipi che mostrano diverse proiezioni di un utente senza ricorrere a parametri di query, ad esempio user/phone-listo /user/mailing-list.

E l'utente 300? È ancora /user/300.

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

POST /user
PUT /user/{id}

DELETE /user/{id}

In conclusione, HTTP può avere una sola risposta a una singola richiesta. Un percorso fa sempre riferimento a qualcosa di singolare.

Per me i plurali manipolano la collezione , mentre i singolari manipolano l' oggetto all'interno di quella collezione.

La raccolta consente i metodi GET / POST / DELETE

L'elemento consente i metodi GET / PUT / DELETE

Per esempio

POST su / studenti aggiungeranno un nuovo studente nella scuola.

DELETE on / studenti rimuoverà tutti gli studenti nella scuola.

ELIMINA su / studente / 123 rimuoverà lo studente 123 dalla scuola.

Potrebbe sembrare poco importante, ma alcuni ingegneri a volte dimenticano l'id. Se il percorso era sempre plurale ed eseguiva un ELIMINA, potresti cancellare accidentalmente i tuoi dati. Considerando che manca l'id sul singolare restituirà un percorso 404 non trovato.

Per espandere ulteriormente l'esempio se l'API dovesse esporre più scuole, allora qualcosa di simile

ELIMINA su / scuola / abc / studenti rimuoverà tutti gli studenti nella scuola abc.

La scelta della parola giusta a volte è una sfida da sola, ma mi piace mantenere la pluralità per la collezione. Ad esempio cart_itemso si cart/itemssente bene. Al contrario cart, eliminando , elimina l'oggetto carrello stesso e non gli oggetti all'interno del carrello;).

Che ne dite di:

/resource/(non /resource)

/resource/ significa che è una cartella contenente qualcosa chiamato "risorsa", è una cartella "resouce".

E penso anche che la convenzione di denominazione delle tabelle del database sia la stessa, ad esempio una tabella chiamata "utente" è una "tabella utente", contiene qualcosa chiamato "utente".

Preferisco usare sia il plurale ( /resources) che il singolare (/resource/{id} ) perché penso che separi più chiaramente la logica tra lavorare sulla raccolta di risorse e lavorare su una singola risorsa.

Come importante effetto collaterale di ciò, può anche aiutare a impedire a qualcuno di utilizzare l'API in modo errato. Ad esempio, considera il caso in cui un utente tenta erroneamente di ottenere una risorsa specificando l'id come parametro come questo:

GET /resources?Id=123

In questo caso, dove utilizziamo la versione plurale, molto probabilmente il server ignorerà il parametro Id e restituirà l'elenco di tutte le risorse. Se l'utente non sta attento, penserà che la chiamata è andata a buon fine e utilizzerà la prima risorsa nell'elenco.

D'altra parte, quando si utilizza la forma singolare:

GET /resource?Id=123

molto probabilmente il server restituirà un errore perché l'id non è specificato nel modo giusto e l'utente dovrà rendersi conto che qualcosa non va.