Convención REST URI: nombre singular o plural del recurso al crearlo

Soy nuevo en REST y he observado que en algunos servicios RESTful utilizan diferentes URI de recursos para actualizar / obtener / eliminar y Crear. Como

• Crear - usando / resources con el método POST (observar plural) en algunos lugares usando / resource (singular)
• Actualización - usando / resource / 123 con el método PUT
• Get - Usando / resource / 123 con el método GET

Estoy un poco confundido acerca de esta convención de nombres de URI. ¿Qué deberíamos usar en plural o singular para la creación de recursos? ¿Cuál debería ser el criterio al decidir eso?

La premisa del uso /resourceses que representa "todos" los recursos. Si lo hace GET /resources, es probable que devuelva la colección completa. Al PUBLICAR en /resources, está agregando a la colección.

Sin embargo, los recursos individuales están disponibles en / resource. Si lo hace GET /resource, probablemente cometerá un error, ya que esta solicitud no tiene ningún sentido, mientras que /resource/123tiene todo el sentido.

Utilizando /resourceen lugar de /resourceses similar a cómo se podría hacer esto si estuviera trabajando con, por ejemplo, un sistema de archivos y una colección de archivos y /resourcees el "directorio" con el individuo 123, 456archivos en ella.

De ninguna manera es correcto o incorrecto, elige lo que más te guste.

Para mí es mejor tener un esquema que pueda asignar directamente al código (fácil de automatizar), principalmente porque el código es lo que va a ser en ambos extremos.

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) 

Tampoco veo el punto de hacer esto y creo que no es el mejor diseño de URI. Como usuario de un servicio RESTful, espero que el recurso de la lista tenga el mismo nombre sin importar si accedo a la lista o al recurso específico 'en' la lista. Debe usar los mismos identificadores sin importar si desea usar el recurso de lista o un recurso específico.

Plural

• Simple : todas las URL comienzan con el mismo prefijo
• Lógico -orders/ obtiene una lista de índice de pedidos.
• Estándar : el estándar más ampliamente adoptado, seguido por la abrumadora mayoría de las API públicas y privadas.

Por ejemplo:

GET /resources - devuelve una lista de elementos de recursos

POST /resources - crea uno o muchos elementos de recursos

PUT /resources - actualiza uno o muchos elementos de recursos

PATCH /resources - actualiza parcialmente uno o muchos elementos de recursos

DELETE /resources - elimina todos los elementos de recursos

Y para elementos de un solo recurso:

GET /resources/:id- devuelve un elemento de recurso específico basado en el :idparámetro

POST /resources/:id - crea un elemento de recurso con la identificación especificada (requiere validación)

PUT /resources/:id - actualiza un elemento de recurso específico

PATCH /resources/:id - actualiza parcialmente un elemento de recurso específico

DELETE /resources/:id - elimina un elemento de recurso específico

Para los defensores del singular, piense de esta manera: ¿Le pediría a alguien algo ordery esperaría una cosa o una lista de cosas? Entonces, ¿por qué esperarías que un servicio devuelva una lista de cosas cuando escribes /order?

Singular

Conveniencia Las cosas pueden tener nombres plurales irregulares. A veces no tienen uno. Pero los nombres singulares siempre están ahí.

por ejemplo, CustomerAddress sobre CustomerAddresses

Considere este recurso relacionado.

Esto /order/12/orderdetail/12es más legible y lógico que /orders/12/orderdetails/4.

Tablas de bases de datos

Un recurso representa una entidad como una tabla de base de datos. Debería tener un nombre lógico singular. Aquí está la respuesta sobre los nombres de las tablas.

Mapeo de clase

Las clases son siempre singulares. Las herramientas ORM generan tablas con los mismos nombres que los nombres de clase. A medida que se utilizan más y más herramientas, los nombres singulares se están convirtiendo en un estándar.

Lea más sobre el dilema de un desarrollador de API REST

Mientras que la práctica más frecuente son las API RESTful donde se usan plurales /api/resources/123, por ejemplo , hay un caso especial en el que encuentro que el uso de un nombre singular es más apropiado / expresivo que los nombres plurales. Es el caso de las relaciones uno a uno. Específicamente si el elemento de destino es un objeto de valor (en el paradigma de diseño impulsado por dominio).

Supongamos que cada recurso tiene un uno a uno accessLogque podría modelarse como un objeto de valor, es decir, no como una entidad, por lo tanto, sin ID. Se podría expresar como /api/resources/123/accessLog. Los verbos habituales (POST, PUT, DELETE, GET) expresarían adecuadamente la intención y también el hecho de que la relación es de hecho uno a uno.

¿Por qué no seguir la tendencia predominante de los nombres de tablas de bases de datos, donde generalmente se acepta una forma singular? He estado allí, hecho eso, reutilicémoslo.

Dilema de nombres de tablas: nombres singulares vs. plurales

Me sorprende ver que tanta gente se subiera al carro del sustantivo plural. Al implementar conversiones de singular a plural, ¿se ocupa de los sustantivos en plural irregulares? ¿Te gusta el dolor?

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

Existen muchos tipos de plural irregular, pero estos son los más comunes:

Tipo de sustantivo Formando el ejemplo plural

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)

Desde la perspectiva del consumidor de API, los puntos finales deben ser predecibles para que

Idealmente...

1. GET /resources debería devolver una lista de recursos.
2. GET /resource debería devolver un código de estado de nivel 400.
3. GET /resources/id/{resourceId} debería devolver una colección con un recurso.
4. GET /resource/id/{resourceId} debería devolver un objeto de recurso.
5. POST /resources debe crear lotes de recursos.
6. POST /resource Debería crear un recurso.
7. PUT /resource debería actualizar un objeto de recurso.
8. PATCH /resource debería actualizar un recurso publicando solo los atributos modificados.
9. PATCH /resources debe actualizar los recursos por lotes y publicar solo los atributos modificados.
10. DELETE /resourcesdebería eliminar todos los recursos; es broma: código de estado 400
11. DELETE /resource/id/{resourceId}

Este enfoque es el más flexible y rico en funciones, pero también el que lleva más tiempo desarrollar. Entonces, si tiene prisa (que siempre es el caso con el desarrollo de software) simplemente nombre su punto final resourceo la forma pluralresources . Prefiero la forma singular porque le da la opción de introspección y evaluación mediante programación, ya que no todas las formas plurales terminan en 's'.

Habiendo dicho todo eso, por cualquier razón, los desarrolladores de práctica más utilizados han elegido usar la forma plural. Esta es, en última instancia, la ruta que he elegido y si nos fijamos en apis populares como githubytwitter , esto es lo que hacen.

Algunos criterios para decidir podrían ser:

1. ¿Cuáles son mis limitaciones de tiempo?
2. ¿Qué operaciones permitiré que hagan mis consumidores?
3. ¿Cómo se ve la carga útil de solicitud y resultado?
4. ¿Quiero poder usar la reflexión y analizar el URI en mi código?

Eso depende de ti. Cualquier cosa que hagas, sé consistente.

Mis dos centavos: los métodos que pasan su tiempo cambiando de plural a singular o viceversa son una pérdida de ciclos de CPU. Puede que sea de la vieja escuela, pero en mi época las cosas se llamaban igual. ¿Cómo busco métodos sobre personas? Ninguna expresión regular cubrirá tanto a personas como a personas sin efectos secundarios indeseables.

Los plurales en inglés pueden ser muy arbitrarios y gravan el código innecesariamente. Cumpla con una convención de nomenclatura. Se suponía que los lenguajes de computadora tenían que ver con la claridad matemática, no con imitar el lenguaje natural.

Prefiero usar la forma singular para la simplicidad y la coherencia.

Por ejemplo, teniendo en cuenta la siguiente url:

/ cliente / 1

Trataré al cliente como una colección de clientes, pero por simplicidad, la parte de la colección se elimina.

Otro ejemplo:

/ equipo / 1

En este caso, equipos no es la forma plural correcta. Por lo tanto, tratarlo como una colección de equipos y eliminar la colección por simplicidad lo hace coherente con el caso del cliente.

Una identificación en una ruta se debe ver igual que un índice a una lista, y la denominación debe proceder en consecuencia.

numbers = [1, 2, 3]

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

Pero algunos recursos no usan identificadores en sus rutas porque solo hay uno o un usuario nunca tiene acceso a más de uno, por lo que no son listas:

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

Con las convenciones de nomenclatura, por lo general es seguro decir "solo elige una y cúmplela", lo cual tiene sentido.

Sin embargo, después de tener que explicar REST a muchas personas, representar los puntos finales como rutas en un sistema de archivos es la forma más expresiva de hacerlo.
No tiene estado (los archivos existen o no existen), jerárquico, simple y familiar: ya sabe cómo acceder a los archivos estáticos, ya sea localmente o mediante http.

Y dentro de ese contexto, las reglas lingüísticas solo pueden llevarlo hasta lo siguiente:

Un directorio puede contener múltiples archivos y / o subdirectorios y, por lo tanto, su nombre debe estar en forma plural.

Y me gusta eso.
Aunque, por otro lado, es su directorio, puede llamarlo "a-resource-or-multiple-resources" si eso es lo que desea. Eso no es realmente lo importante.

Lo importante es que si coloca un archivo llamado "123" en un directorio llamado "resourceS" (resultante /resourceS/123), no puede esperar que sea accesible a través de /resource/123.

No intente hacerlo más inteligente de lo que debe ser: cambiar de plural a singular dependiendo del recuento de recursos a los que está accediendo actualmente puede ser estéticamente agradable para algunos, pero no es efectivo y no tiene sentido en un jerárquico sistema

Nota: Técnicamente, puede hacer "enlaces simbólicos", para que /resources/123también se pueda acceder a través de ellos /resource/123, ¡pero el primero todavía tiene que existir!

Eche un vistazo a la Guía de diseño de API de Google : Nombres de recursos para otra versión de los recursos de nombres.

En breve:

• Las colecciones se nombran con plurales.
• Los recursos individuales se nombran con una cadena.

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

Vale la pena leerlo si estás pensando en este tema.

El uso del plural para todos los métodos es más práctico al menos en un aspecto: si está desarrollando y probando una API de recursos utilizando Postman (o una herramienta similar), no necesita editar el URI al cambiar de GET a PUT a POST, etc. .

Ambas representaciones son útiles. Había usado singular por conveniencia durante bastante tiempo, la inflexión puede ser difícil. Mi experiencia en el desarrollo de API REST estrictamente singulares, los desarrolladores que consumen el punto final carecen de certeza sobre cuál puede ser la forma del resultado. Ahora prefiero usar el término que mejor describe la forma de la respuesta.

Si todos sus recursos son de nivel superior, entonces puede salirse con representaciones singulares. Evitar la inflexión es una gran victoria.

Si está haciendo algún tipo de enlace profundo para representar consultas sobre relaciones, entonces los desarrolladores que escriben en contra de su API pueden recibir una convención más estricta.

Mi convención es que cada nivel de profundidad en un URI está describiendo una interacción con el recurso padre, y el URI completo debe describir implícitamente lo que se está recuperando.

Supongamos que tenemos el siguiente modelo.

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

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

Si tuviera que proporcionar un recurso que permita a un cliente obtener el administrador de un amigo en particular de un usuario en particular, podría ser algo como:

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

Los siguientes son algunos ejemplos más:

• GET /users - enumere los recursos de usuario en la colección global de usuarios
• POST /users - Crear un nuevo usuario en la colección global de usuarios
• GET /users/{id} - recuperar un usuario específico de la colección de usuarios globales
• GET /users/{id}/manager - obtener el administrador de un usuario específico
• GET /users/{id}/friends - obtener la lista de amigos de un usuario
• GET /users/{id}/friends/{friendId} - obtener un amigo específico de un usuario
• LINK /users/{id}/friends - agregar una asociación de amigos a este usuario
• UNLINK /users/{id}/friends - eliminar una asociación de amigos de este usuario

Observe cómo cada nivel se asigna a un padre sobre el que se puede actuar. Usar diferentes padres para el mismo objeto es contraintuitivo. La recuperación de un recurso en GET /resource/123no deja ninguna indicación de que la creación de un nuevo recurso deba realizarsePOST /resources

Sé que la mayoría de las personas están entre decidir si usar plural o singular. El problema que no se ha abordado aquí es que el cliente necesitará saber cuál está utilizando, y es probable que siempre cometan un error. De aquí viene mi sugerencia.

¿Qué tal ambos? Y con eso, me refiero a usar singular para toda su API y luego crear rutas para reenviar solicitudes hechas en forma plural a la forma singular. Por ejemplo:

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

Te dan la imagen. Nadie se equivoca, con un esfuerzo mínimo, y el cliente siempre lo hará bien.

No me gusta ver que la {id}parte de las URL se superponga con los recursos secundarios, ya idque en teoría podría ser cualquier cosa y habría ambigüedad. Está mezclando diferentes conceptos (identificadores y nombres de sub-recursos).

Cuestiones similares se ve a menudo en enumlas constantes o carpeta estructuras, donde los diferentes conceptos se mezclan (por ejemplo, cuando se tiene carpetas Tigers, Lionsy Cheetahs, y luego también una carpeta llamada Animalsal mismo nivel - esto no tiene sentido que uno es un subconjunto de la otro).

En general, creo que la última parte nombrada de un punto final debería ser singular si se trata de una sola entidad a la vez, y plural si se trata de una lista de entidades.

Entonces, los puntos finales que tratan con un solo usuario:

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

Luego hay un recurso separado para hacer consultas a los usuarios, que generalmente devuelven una lista:

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

Y aquí algunos ejemplos de un sub-recurso que trata con un usuario específico:

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

Hacer un amigo (enlace de muchos a muchos):

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

Nunca hay ambigüedad, y la denominación plural o singular del recurso es una pista para el usuario de lo que puede esperar (lista u objeto). No hay restricciones en ids, lo que teóricamente hace posible tener un usuario con la identificación newsin superponerse con un (posible futuro) nombre de sub-recurso.

Use Singular y aproveche la convención en inglés que se ve, por ejemplo, en "Directorio de negocios".

Muchas cosas se leen de esta manera: "Book Case", "Dog Pack", "Art Gallery", "Film Festival", "Car Lot", etc.

Esto coincide convenientemente con la ruta de la url de izquierda a derecha. Tipo de artículo a la izquierda. Establecer tipo a la derecha.

¿ GET /usersRealmente alguna vez busca un conjunto de usuarios? No Usualmente. Obtiene un conjunto de apéndices que contienen una clave y quizás un nombre de usuario. Entonces no es realmente de /userstodos modos. Es un índice de usuarios, o un "índice de usuarios" si lo desea. ¿Por qué no llamarlo así? Es un /user/index. Como hemos nombrado el tipo de conjunto, podemos tener múltiples tipos que muestran diferentes proyecciones de un usuario sin recurrir a parámetros de consulta, por ejemplo, user/phone-listo /user/mailing-list.

¿Y qué hay del usuario 300? Aun esta /user/300.

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

POST /user
PUT /user/{id}

DELETE /user/{id}

Para terminar, HTTP solo puede tener una respuesta única a una sola solicitud. Un camino siempre se refiere a algo singular.

Para mí, los plurales manipulan la colección , mientras que los singulares manipulan el elemento dentro de esa colección.

La colección permite los métodos GET / POST / DELETE

El elemento permite los métodos GET / PUT / DELETE

Por ejemplo

POST en / estudiantes agregará un nuevo estudiante en la escuela.

BORRAR en / estudiantes eliminará a todos los estudiantes en la escuela.

BORRAR el / estudiante / 123 eliminará al estudiante 123 de la escuela.

Puede parecer poco importante, pero algunos ingenieros a veces olvidan la identificación. Si la ruta siempre fue plural y realizó una BORRADO, podría borrar accidentalmente sus datos. Mientras que la falta de la identificación en singular devolverá una ruta 404 no encontrada.

Para ampliar aún más el ejemplo si se suponía que la API exponía varias escuelas, entonces algo como

ELIMINAR en / escuela / abc / estudiantes eliminará a todos los estudiantes en la escuela abc.

Elegir la palabra correcta a veces es un desafío en sí mismo, pero me gusta mantener la pluralidad de la colección. Por ejemplo, cart_itemso se cart/itemssiente bien. Por el contrario cart, la eliminación elimina el objeto del carrito y no los artículos dentro del carrito;).

Qué tal si:

/resource/(no /resource)

/resource/ significa que es una carpeta que contiene algo llamado "recurso", es una carpeta de "recursos".

Y también creo que la convención de nomenclatura de las tablas de la base de datos es la misma, por ejemplo, una tabla llamada 'usuario' es una "tabla de usuario", contiene algo llamado "usuario".

Prefiero usar tanto plural ( /resources) como singular (/resource/{id} ) porque creo que separa más claramente la lógica entre trabajar en la recopilación de recursos y trabajar en un solo recurso.

Como un efecto secundario importante de esto, también puede ayudar a evitar que alguien use la API incorrectamente. Por ejemplo, considere el caso en el que un usuario intenta obtener un recurso por error al especificar el Id como un parámetro como este:

GET /resources?Id=123

En este caso, donde usamos la versión plural, el servidor probablemente ignorará el parámetro Id y devolverá la lista de todos los recursos. Si el usuario no tiene cuidado, pensará que la llamada fue exitosa y usará el primer recurso de la lista.

Por otro lado, cuando se usa la forma singular:

GET /resource?Id=123

lo más probable es que el servidor devuelva un error porque el Id no está especificado de la manera correcta y el usuario tendrá que darse cuenta de que algo está mal.