REST URI convention-Nombre singular o plural del recurso al crearlo

Para mí es mejor tener un esquema que se puede 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 sentido de hacer esto y creo que no es el mejor diseño de URI. Como usuario de un servicio RESTful, esperaría que el recurso de la lista tuviera el mismo nombre, sin importar si accedo a la lista o a un recurso específico 'en' la lista. Debe usar los mismos identificadores sin importar si desea usar el recurso de la lista o un recurso específico.

Plural

• Simple - todas las url comienzan con el mismo prefijo
• Lógico - orders/ obtiene una lista índice de órdenes.
• Estándar - 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 varios recursos

PUT /resources - actualiza uno o muchos recursos

PATCH /resources - actualiza parcialmente uno o varios recursos

DELETE /resources - elimina todos los elementos de recursos

Y para los recursos únicos:

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

POST /resources/:id - crea un elemento de recurso con id especificado (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, piénsenlo de esta manera: ¿Le pedirían a alguien un order y esperarían una cosa, o una lista de cosas? Entonces, ¿por qué esperas que un servicio devuelva una lista de cosas cuando escribes /order?

Mientras que la práctica más frecuente son las api RESTful donde se usan plurales , por ejemplo, /api/resources/123, hay un caso especial donde 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 basado en el dominio).

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

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.

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

Tablas de base 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 la tabla nombre.

Asignación de clases

Las clases son siempre singulares. Las herramientas OR 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.

Leer más sobre El dilema de un desarrollador de API REST

¿Por qué no seguir la tendencia prevalente de los nombres de tablas de bases de datos, donde una forma singular es generalmente aceptada? He estado allí, hecho eso reuse vamos a reutilizar.

Dilema de Nomenclatura de la Tabla: Nombres singulares vs. Plurales

Desde la perspectiva del consumidor de API, los endpoints deben ser predecibles para

Idealmente...

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

Este enfoque es el más flexible y rico en características, pero también el que requiere más tiempo para desarrollarse. Por lo tanto, si tiene prisa (que siempre es el caso con el desarrollo de software) simplemente nombre su punto final resource o la forma plural resources. Prefiero la forma singular porque te da la opción de hacer introspección y evaluar programáticamente ya que no todas las formas plurales terminan en 's'.

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

Algunos criterios para decidir podrían be:

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

Así que depende de ti. Sea lo que sea que hagas, sé consistente.

Me sorprende ver que tanta gente se subiría al carro del sustantivo plural. Al implementar conversiones de singular a plural, ¿estás cuidando los sustantivos plurales irregulares? ¿Te gusta el dolor?

Véase http://web2.uvcs.uvic.ca/elc/studyzone/330/grammar/irrplu.htm

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

Tipo de sustantivo Que forma el Ejemplo plural

Termina con-fe Cambiar f a v entonces Cuchillo Add-s cuchillo la vida vive esposa esposas Termina con-f Cambiar f a v entonces Añadir-es mitad mitades lobo lobos panes de pan Termina con-o Añadir-es patatas patatas tomate tomates los volcanes del volcán termina con-us Change-us to-i cactus cactus núcleo núcleos focus foci termina con-es Cambio-es a-es análisis análisis crisis crisis tesis tesis termina con-on Cambio-on a-un fenómeno fenómenos criterio criterios TODOS LOS TIPOS Cambian la vocal o Cambiar el palabra o Añadir un final diferente hombre hombres pies pies niño los niños persona personas dientes ratón, ratones Singular y plural inmutable son las mismas ovejas ciervo pescado (a veces)

Prefiero usar la forma singular por simplicidad y consistencia.

Por ejemplo, considerando la siguiente url:

/cliente/1

Trataré al cliente como colección del cliente, pero para simplificar, la parte de colección se elimina.

Otro ejemplo:

/equipment/1

En este caso, equipments 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 cliente caso.

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 puedo buscar métodos relativos a las personas? Ninguna expresión regular cubrirá tanto a la persona como a las personas sin efectos secundarios indeseables.

Los plurales en inglés pueden ser muy arbitrarios y sobrecargan el código innecesariamente. Apégate a una convención de nombres. Se suponía que los lenguajes de computación claridad matemática, no se trata de imitar el lenguaje natural.

Con las convenciones de nomenclatura, por lo general es seguro decir "solo elige uno y apégate a él", lo que tiene sentido.

Sin embargo, después de tener que explicar REST a muchas personas, representar endpoints como rutas en un sistema de archivos es la forma más expresiva de hacerlo.
Es sin 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 a través de http.

Y en ese contexto, las normas lingüísticas solo puede llegar hasta lo siguiente:

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

Y eso me gusta.
Aunque, por otro lado-es tu directorio, puedes nombrarlo "un recurso-o-múltiples-recursos" si eso es lo que quieres. Eso no es realmente lo importante.

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

No trate de hacerlo más inteligente de lo que tiene que ser - cambiar de plural a único dependiendo de la cantidad 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 sistema jerárquico.

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

Sé que la mayoría de la gente está 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 siempre es probable que cometa un error. De ahí 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
...

Se obtiene el imagen. Nadie está equivocado, un esfuerzo mínimo, y el cliente siempre lo hará bien.

Usar plural para todos los métodos es más práctico al menos en un aspecto: si estás desarrollando y probando una API de recursos usando Postman (o una herramienta similar), no necesitas 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 en lo que la forma del resultado puede ser. 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 la suya con representaciones singulares. Evitar la inflexión es un gran ganar.

Si está haciendo algún tipo de enlace profundo para representar consultas sobre relaciones, entonces los desarrolladores que escriben contra su API pueden ser ayudados por tener 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 debería 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 necesitaba proporcionar un recurso que permita a un cliente obtener el administrador de un amigo en particular de un usuario en particular, podría verse algo como:

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

Los siguientes son algunos ejemplos más:

• GET /users - listar 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 global de usuarios
• GET /users/{id}/manager - obtener el gestor 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 - añadir 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. Recuperar un recurso en GET /resource/123 no deja ninguna indicación de que la creación de un nuevo recurso debe hacerse en POST /resources

Qué tal:

/resource/ (no /resource)

/resource/ significa que es una carpeta que contiene algo llamado "resource", es una carpeta" resouce".

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

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

Collection permite los métodos GET / POST / DELETE

Item permite los métodos GET / PUT / DELETE

Por ejemplo

POST on /students agregará un nuevo estudiante a la escuela.

DELETE on /students eliminará a todos los estudiantes de la escuela.

SUPRÍMASE el /student / 123 eliminará al estudiante 123 de la escuela.

Puede parecer poco importante, pero algunos ingenieros a veces olvidan el id. Si la ruta siempre fue plural y realizó una ELIMINACIÓN, es posible que borre accidentalmente sus datos. Mientras que perder el id en singular devolverá una ruta 404 no encontrada.

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

ELIMINAR en /school / abc / students eliminará todos los estudiantes de la escuela abc.

Elegir la palabra correcta a veces es un desafío por sí solo, pero me gusta mantener la pluralidad de la colección. Por ejemplo, cart_items o cart/items se siente bien. Por el contrario, al eliminar cart, elimina el objeto del carrito por sí mismo y no los elementos dentro del carrito ;).

Prefiero usar tanto plural (/resources) como singular (/resource/{id}) porque creo que separa más claramente la lógica entre trabajar en la colecció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 erróneamente obtener un recurso especificando el Id como un parámetro como este:

GET /resources?Id=123

En este caso, donde usamos la versión plural, lo más probable es que el servidor ignore el parámetro Id y devuelva 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 se especifica de la manera correcta, y el usuario tendrá que darse cuenta de que algo está mal.