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


529

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?


99
Siguiendo este tema, he recopilado algunos ejemplos de famosas API REST en un artículo: inmensosofa.blogspot.com/2011/10/… .
jjmontes

3
La conclusión a la que llegué después de leer todas las respuestas a continuación: Siempre use singular porque (a) es consistente, (b) se asigna directamente a nombres de clases y tablas singulares, (c) algunos sustantivos plurales son irregulares (impredecibles) en inglés
Will Sheppard

Vea esta respuesta para obtener un enlace a convenciones de nombres de tablas singulares, y hay otro artículo que menciona este problema exacto Dilema del desarrollador de Rest API - gracias @Sorter
Will Sheppard

Respuestas:


281

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.


55
¡Gran respuesta! Pero los directorios "predeterminados" en Windows tienen nombres plurales . Como "Archivos de programa", "Usuarios", "Documentos", "Videos", etc. También he encontrado nombres plurales en URL de sitios web con mucha más frecuencia.
Dmitry Gonchar

50
La convención de facto que la mayoría de las personas y las API utilizan es mantenerla plural en todo momento. Los Id. Especifican UN recurso de coches / id
PositiveGuy

205
"De ninguna manera es correcto o incorrecto, ve con lo que más te gusta". Ah, la famosa frase que escucho tan a menudo y me canso y me canso de escuchar a la gente. Las convenciones importan y DEBEN debatirse de manera constructiva entre la comunidad, de ahí surgen mejores soluciones y buenas prácticas. Cuando usa tanto el plural como el singular para los nombres de recursos en URI, complica su código y la API porque el usuario y el código detrás de la API tienen que dar cuenta de eso en las rutas y la lógica para diferenciar solo vs plural, mientras que si solo se queda con plural todo el tiempo no tienes problemas.
PositiveGuy

30
@TomaszPluskiewicz Tienes toda la razón de que clientes no les importa. Como desarrolladores de software , deberíamos preocuparnos, y por eso estoy de acuerdo con el comentario de WTF de que los debates constructivos sobre la convención son valiosos.
Travis D

12
Entonces, ¿alguien puede poner una respuesta de una palabra y aceptarla para que no tenga que leer todo esto (nuevamente).
Ben George

624

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) 

22
La dificultad o facilidad de esto se debe a no respetar a HATEOS. No debería importar si es plural o singular o cualquier otra cosa. Debe respetar los uri enviados desde el servidor y no "construir" su uri en el cliente. Entonces tienes 0 mapeo que hacer para tu código.
Richard

77
@richard El cliente todavía tiene que hacer mapeo. En HATEOS tendrían que asignar un nombre que represente la relación (rel) con la construcción de URI. El rel, método (verbo) y Content-Type forman los medios de recursos. Esto no excluye la necesidad de un buen diseño de URI. Aunque el cliente podría dar prioridad al nombre rel, los desarrolladores de la API todavía necesitan un buen estándar legible para la construcción de URI.

44
Esta es una mejor respuesta en mi opinión. Excepto que siempre he preferido usar Singular en lugar de plural. User.getList (), User.getById, User.delete, etc.
Eastern Monk

3
Me gusta la simplicidad. El mapeo también tiene la ventaja de hacer que la documentación y las pruebas en las rutas sean increíblemente fáciles de escribir.
delos

55
Esto tiene sentido para mí. Sin embargo, somos una tienda de base de datos primero, lo que significa que generamos código y entidades api a partir de nuestro esquema de base de datos. Y los estándares de bases de datos tienden a abogar por nombres de tablas singulares, por lo que vamos con eso, pero todavía bajo la misma lógica que esta respuesta.
André C. Andersen

274

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.


69
Esta es la mejor respuesta en lo que a mí respecta. Aprecio que a los diseñadores de API les guste la corrección lingüística de decir "obtener el recurso # 123", pero es una molestia de codificación adicional al escribir clientes de la API, así como documentación de ayuda. (GET / api / people vs. GET / api / person / 123? Euuuchh.) .... en lugar de pensarlo como "obtener el recurso # 123", dígalo en su cabeza como "obtener de la colección de recursos que coincide con # 123 ".
Warren Rumak

55
Distinguir recursos plurales / singulares no se trata de corrección lingüística sino de escala. / employee / 12 me lee como el subconjunto del recurso de empleados con id '12' (podría significar cualquier cosa, por ejemplo, una consulta de búsqueda guardada en empleados despedidos recientemente). Si lee lo anterior como el empleado con la identificación '12', ¿cómo representaría el subconjunto? La única opción es hacer que las URI sean colecciones de mineral más complejas que contienen objetos de los objetos mismos (es decir, singular frente a plural).
Erik

99
Elegir / empleados / 12 para representar una consulta de búsqueda en empleados despedidos recientemente (o cualquier subconjunto) sería un mal diseño, creo. Si desea representar subconjuntos de cualquier tipo, sugiero presentarlos como recursos (con nombres propios) por derecho propio.
Jan Deinhard

3
Esto no tiene nada que ver con la comprensibilidad para los clientes. Se trata de abordar diferentes cosas con diferentes URL. Y poder responder a todos los métodos HTTP sin estar en conflicto. Puede tener un recurso que sea una colección de elementos y un recurso que represente un elemento en sí mismo. Por lo que me importa, el recurso de colecciones podría ser example.org/166316e2-e1 y un elemento en particular en esa colección example.org/20d68348-ccc-001c4200de . El cliente no debe construir URL (eso obviamente no escala, no es RESTful y para eso están los tipos de relación de enlace).
Erik

44
Si no cree que las URL arbitrarias sean bonitas, no dude en identificar un recurso de colección con un nombre plural y un elemento individual con un nombre singular. Si no le gustan las URL en inglés y su idioma natural no admite esa forma de notación individual / plural, use otra cosa para definirlo en su idioma preferido, supongo que todos los idiomas le permitirán distinguir de alguna manera '/ the-collection-of- bla / 2321 'versus' bla / 61 'por escrito. Y cada uno de esos dos recursos diferentes representan resultados completamente diferentes al enviar GET / PUT / DELETE / POST / PATCH y otros.
Erik

77

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?


10
Singular : en caso de que una parte de su sistema sea solo un objeto (0-1, existe o no), por ejemplo, usuarios / 1 / avatar, puede usar una forma singular para etiquetar este único objeto (por ejemplo, avatar). Un ejemplo más detallado aquí: stackoverflow .com / a / 38296217/860099 . Por cierto, muy buena respuesta :)
Kamil Kiełczewski

¿Qué pasa con la asignación de nombres de clase y tabla, que deberían ser singulares? (ver otra respuesta )
Will Sheppard

@WillSheppard: los nombres de clase son mejores en forma singular y los nombres de tabla son mejores en forma plural. Por ejemplo, Orderes un buen nombre para una clase que trata con instancias singulares de objetos que se refieren a un orden. OrderListes un nombre para una clase que trata con múltiples Orderinstancias. Orders Tablees un buen nombre para una tabla de base de datos de muchos pedidos.
Eric Knudtson

Quiero OBTENER / pedidos pero solo quiero / 1
jim smith

@ jim-smith entonces ¿por qué no solicitas / 1 de la colección de usuarios con GET / users / 1?
Rohmer

49

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


39
Los nombres singulares siempre están ahí /clothe/12/trouser/34 :)
Gert Arnold

18
@GertArnold la palabra clothees un verbo. Las API de descanso generalmente se adhieren a los sustantivos cuando hablan de recursos y usan verbos al describir acciones. La forma singular es clout, pero es arcaica y probablemente sería reemplazada más adecuadamente por garment.
Steve Buzonas

@SteveBuzonas ¿Y para pantalones y gafas de sol?
Koray Tugay

32

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.


44
Buen intento. Pero sería mejor como "accessLogEntries". :-)
Tom Russell

8
@TomRussell ¿por qué? Las implicaciones de esto son importantes. Entiendo por qué usaría el plural incluso cuando está accediendo a un recurso por un identificador, pero para muchos-a-uno o uno a uno es bastante engañoso. Considere una API que administre a los miembros del personal para una empresa con múltiples ubicaciones. Cada miembro del personal trabaja en una ubicación. GET /users/123/locationdebe buscar la ubicación en la que trabaja el usuario. ¿No es GET /users/123/locationsrealmente engañoso como consumidor?
Carrie Kendall

1
@CarrieKendall veo tu punto. Como accessLogse modela como un atributo o valor, en lugar de una entidad, debería ser singular. Si se le da un exceso de ingeniería, entonces una entrada de registro sería una entidad y tendría /api/accessLogEntries?resource=123.
Tom Russell el

De acuerdo, aunque, creo que rompe la convención de pluralizar todas las cosas. Es complicado. Para mí, es importante que una API sea sencilla, es decir, la documentación debe complementar una implementación ya directa.
Carrie Kendall el

Soy más un programador que una persona de sistemas o bases de datos, así que me gusta una API que cuenta una historia en lugar de adherirse a la convención. Sin embargo, las implicaciones para la documentación automatizada son reales.
Tom Russell el

26

¿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


8
Das Auto es mucho mejor que Die Autos. Además, las convenciones plurales en inglés no son consistentes.
FlavorScape

77
El espacio de nombres de recursos es una cuestión de semántica, no de implementación. Entonces, usar la analogía de las tablas DB, no es muy afortunado. Además, cuando trabajas con DB-s estás manipulando solo tablas, aunque, por supuesto, puedes afectar el contenido (filas), pero en REST no hay ninguna restricción para manipular un solo recurso directamente.
arpadf

3
Creo que esta es una buena analogía, pero más importante que decidir si ir en singular o plural es ser coherente con lo que elija. No va a insertar en Usuarios y luego seleccionar de Usuario. La misma regla debe aplicarse a los recursos REST: no los renombre según lo que esté haciendo.
Todd Menier

3
No son solo nombres de tablas, también son comparables a los nombres de clase en OO (mi clase se llamaría Cliente, no Clientes).
bytedev

En este caso, la semántica es demasiado importante para simplemente aceptar tendencias "ya definidas"
Cattani Simone

19

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)

55
No entiendo la preocupación aquí. No se supone que cambiemos singular a plural programáticamente. La mayoría de las formas plurales anteriores son bien conocidas y no deberían ser motivo de preocupación. Si alguien tiene poco conocimiento de inglés, deletreará incorrectamente cualquier parte de su variable. Además, siguiendo su lógica, ¿también recomienda usar formas singulares para referir colecciones en el código fuente también?
Kishor borate

1
Hay palabras en inglés que son irregulares hasta el punto de que a menudo es un problema incluso dentro de la Anglosfera y son términos comúnmente utilizados como índice / índices / índices, vértices / vértices / vértices, matriz / matrices / matrices, radio / radios / radios, etc. No veo el punto de hacer que las rutas REST sean plurales de todos modos, porque si todas son consistentemente singulares, es más obvio para todos.
maldito

@kishorborate, el uso del plural como URI es más propenso a errores, incluso para hablantes nativos de inglés. Como indica damd, los plurales como index / indexes / indices están introduciendo más problemas. Y hay innumerables sustantivos. Mezclar sustantivos incontables con plurales es otro problema. ¿Por qué es más difícil para los programadores dedicar más tiempo a esto? Sugiero usar singulares para todo. Si hay un / {id}, entonces la API debería devolver un solo registro. Si no hay un / {id} que sigue, entonces la API debería devolver la colección.
Daming Fu

3
El recurso Singular @DamingFu no siempre tiene una identificación asociada. p.ej. / user / {id} / nickName Al mirarlo, no está claro si devolverá la lista de nickNames o un solo nickName? Por lo tanto, las API son más intuitivas cuando usa formas plurales. Sí, pocas palabras tendrán formas plurales irregulares. Para alguien que está leyendo la forma plural, no es un problema. Es un problema solo cuando se escribe la firma API. Pero la frecuencia de tales palabras no es alta, además, encontrar la forma plural de cualquier palabra no lleva mucho tiempo. Es una compensación que deberíamos aceptar, para que las API sean más intuitivas.
kishor borate

15

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.


1
Parece que se ha elegido la forma plural porque los desarrolladores parecen suponer que todos los recursos son inherentemente parte de alguna colección. Sin embargo, la "convención aceptada" parece indicar que POST /usersdebería crear un solo usuario, agregándolo a la colección. Estoy en desacuerdo. POST /usersdebería crear una lista de usuarios (incluso si es una lista de 1), donde POST /userdebería crear exactamente un usuario. No veo ninguna razón por la cual los puntos finales de recursos en plural y singular no puedan coexistir. Describen diferentes comportamientos y no deberían sorprender a nadie de su función.
enamorado

¿No hay una convención para especificar un ID de recurso en la ruta? Si es así, parece estar ampliamente descuidado. Por ejemplo, POST users/<id>crearía un nuevo usuario.
Tom Russell el

1
@TomRussell por lo general, el servidor crea la identificación, por lo que aún no conoce la identificación para PUBLICAR.
Alex

3
@TomRussell, cuando el cliente determina (una especie de) identificación al crear un nuevo recurso, es más común usarlo en PUT /users/<id>lugar de hacerlo POST. POSTtiene la interpretación "agregue esto a la colección y determine la identificación como parte de eso". PUTtiene la interpretación "actualizar (o agregar) este recurso con esta identificación". Ver restcookbook.com/HTTP%20Methods/put-vs-post para una explicación más larga de este principio.
Jochem Schulenklopper

No creo que la comparación con Twitters API sea justa, ya que utilizan la forma Plural para todos sus puntos finales. No mezclan Plural y Singular para los mismos Elementos.
Andrew T Finnell

7

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.


2
Esto aborda el código que intenta "autogenerar / alterar puntos finales" (hay muchas bibliotecas con opiniones que asumen pluralidad / singularidad e intentan mapear); sin embargo, esto se aplica a los nombres de punto final elegidos explícitamente más allá de elegir la palabra correcta (independientemente de cómo esté pluralizado).
user2864740

6

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.


2
POST / cliente parece que va a reemplazar al único cliente. Este es mi mayor dolor al usar nombres de recursos singulares.
Andrew T Finnell

2
@ andrew-t-finnell ¿No se POST /customersupone que haga lo mismo: insertar un solo cliente?
donmutti

Inserta un único Cliente en una colección de Clientes. POST /customerme lee como si fuera POST'ing al thecliente. No es una colección de clientes. Sin embargo, admito que Plural o no Plural es una preferencia. Mientras no se mezclen como la otra respuesta. Eso sería increíblemente confuso.
Andrew T Finnell

"PUBLICAR al cliente" no tiene sentido en este caso. POST no reemplaza, se inserta. Tal vez si fuera POST / customer / 1 podría ver el dilema, pero incluso eso no tiene mucho sentido desde una perspectiva REST, porque ¿qué estás insertando? Sería / cliente / 1 / factura o / cliente / 1 / recibo, etc.
maldito

5

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

4

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!


3

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        | /name@example.com | /settings     | /customFrom  |
| //storage.googleapis.com | /buckets      | /bucket-id        | /objects      | /object-id   |
|--------------------------+---------------+-------------------+---------------+--------------|

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


2

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


1
No es un argumento para mí, ya que Postman ofrece colecciones, por lo que puede guardar todos los recursos como diferentes elementos de colección y probarlos individualmente. Todo lo que debe hacer es seleccionar un recurso de la colección, no tiene que editar parámetros / métodos / etc. cada vez.
Wirone

1

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


1

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.


1
Si está haciendo redireccionamientos 302 y su caché está almacenando todo dos veces, ha configurado su caché incorrectamente. No se supone que la memoria caché almacene 302 redirecciones.
wynnset

2
Si su cliente siempre usa /resourcesy siempre es redirigido /resource, lo ha hecho mal. Si alguien más usa su API, puede usar la URL correcta directamente o ser redirigido (lo que funciona pero está mal) y fue usted quien abrió el camino incorrecto.
maaartinus

No estoy seguro de lo que quieres decir con "incorrecto", eso es muy subjetivo. No está realmente mal porque funciona.
wynnset

Esto aumenta el costo de mantenimiento, el costo de comprensión y la cantidad de código requerida.
Will Sheppard

1

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.


1

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.


-1

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;).


¿No debería dividirse esto en / cart y / cart / item (s) de todos modos? Entonces, ¿puede abordar todo el carrito (por ejemplo, con una eliminación) o artículos individuales?
Rob Grant

@RobertGrant ¿No sería eso "/ carts / items / 123"? (p. ej., ¿por qué "carro" y no "carros" es que la regla es 'siempre plural'?)
usuario2864740

1
Yo diría que si se registra el código de producción que puede realizar una eliminación de los artículos del carrito de todos, hay problemas más grandes que la convención de nomenclatura. La posibilidad de que recuerden una 's' sobre una identificación es mucho menor.
Andrew T Finnell

¿Alguien crearía un punto final que simplemente elimine una colección completa? Parece extremadamente peligroso para mí, y probablemente también por qué REST realmente no admite eliminaciones por lotes. (tendrías que envolver la matriz en un objeto). Si realmente necesitaba un punto final para eliminar una colección completa, me aseguraría de que el URI fuera muy único y definitivamente no similar a POST
cnps

-1

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".


-2

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.


1
¿Por qué estás mezclando modismos aquí? ¿Utiliza la notación URI adecuada en el primer párrafo y luego cambia a los parámetros de consulta? El uso de parámetros de consulta para obtener un recurso con un ID de 123 está completamente fuera de lugar aquí.
Andrew T Finnell

Eso fue claramente un error. He actualizado mi respuesta ahora. Gracias por notarlo.
pberggreen

Después de ser rechazado nuevamente, miré lo que escribí y me di cuenta de que la publicación original era correcta. Mi punto era exactamente que si el usuario hace algo incorrecto, entonces usar plural + singular de hecho dará un mejor mensaje de error que usar solo plural.
pberggreen

Todavía siento que esto está confundiendo el tema en cuestión. La idea de usar el plural es que es una colección. Y el número al final es un índice en la colección. ¿Qué pasa si obtienes / recurso por sí mismo? Usar tanto el plural como el singular juntos es bastante confuso. Diciendo / resources / 123 dice: Obtenga mi recurso 123 en el depósito de recursos.
Andrew T Finnell
Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.