Resumen
Los nombres de recursos de las API REST deben ser plurales. Usa /pets/{id}, no /pet/{id}. Los nombres plurales representan colecciones de forma consistente, se alinean con la semántica HTTP y coinciden con la forma en que los desarrolladores piensan sobre los recursos. La Modern PetstoreAPI utiliza nombres plurales en todo su diseño de API, siguiendo las mejores prácticas de la industria.
Introducción
Estás diseñando una API REST. Necesitas un endpoint para obtener un usuario por ID. ¿Usas /user/123 o /users/123? Esta pregunta ha provocado innumerables debates, hilos de Stack Overflow y discusiones de equipo.
La respuesta es clara: usa el plural. Pero entender el porqué es más importante que memorizar la regla. El razonamiento conecta con cómo funciona REST, cómo se comportan las colecciones y cómo los desarrolladores piensan sobre los recursos.
La antigua Swagger Petstore lo hizo mal, usando /pet/{id} en lugar de /pets/{id}. Esta inconsistencia enseñó a millones de desarrolladores el patrón incorrecto. Modern PetstoreAPI corrige esto usando nombres plurales consistentemente en todos los endpoints.
En esta guía, aprenderás por qué los nombres plurales son la elección correcta, cómo se alinean con los principios REST y cómo implementarlos correctamente usando Modern PetstoreAPI como referencia.
El Debate Plural vs Singular
El debate existe porque ambos enfoques parecen lógicos a primera vista.
El Argumento Singular
“Cuando solicito /user/123, obtengo un usuario, no múltiples usuarios. El singular tiene sentido.”
Este razonamiento se centra en la respuesta: estás obteniendo un solo recurso, por lo que la URL debería ser singular.
El Argumento Plural
“La URL representa una colección. /users es la colección de todos los usuarios. /users/123 es el elemento 123 de esa colección.”
Este razonamiento se centra en la estructura del recurso: las URLs representan colecciones, y estás accediendo a elementos dentro de esas colecciones.
Por qué esto importa
Tu elección afecta:
- Consistencia de la API - La mezcla de nombres confunde a los desarrolladores
- Modelos mentales - Cómo los desarrolladores entienden la estructura de tu API
- Generación de código - Las herramientas generan código cliente basado en los nombres de los recursos
- Claridad de la documentación - La documentación debe explicar tu lógica de nomenclatura
Por qué los Nombres Plurales Ganan
Los nombres de recursos plurales se alinean con los principios REST y la semántica HTTP. Aquí te explicamos por qué.
1. Las Colecciones Son Plurales
En REST, los recursos son colecciones. Cuando accedes a /users, estás accediendo a la colección de usuarios. Cuando accedes a /users/123, estás accediendo al elemento 123 de la colección de usuarios.
GET /users ← La colección de usuarios
GET /users/123 ← Elemento 123 en la colección de usuarios
POST /users ← Añadir a la colección de usuarios
DELETE /users/123 ← Eliminar el elemento 123 de la colección de usuarios
Este modelo mental es consistente. La colección es siempre /users, ya sea que estés accediendo a todos los elementos o a un solo elemento.
Con nombres singulares, el modelo mental se rompe:
GET /user ← ¿Qué usuario?
GET /user/123 ← Esto tiene sentido
POST /user ← Añadir a... ¿qué?
2. Los Métodos HTTP Operan sobre Colecciones
Los métodos HTTP describen operaciones sobre colecciones:
GET /users- Recuperar la colecciónPOST /users- Añadir a la colecciónGET /users/123- Recuperar el elemento 123 de la colecciónPUT /users/123- Reemplazar el elemento 123 en la colecciónDELETE /users/123- Eliminar el elemento 123 de la colección
La colección es el recurso. Los elementos individuales son miembros de esa colección.
3. Consistencia entre Endpoints
Los nombres plurales crean consistencia:
GET /pets ← Colección
GET /pets/123 ← Elemento en la colección
GET /orders ← Colección
GET /orders/456 ← Elemento en la colección
Los nombres singulares te obligan a cambiar entre singular y plural:
GET /pet ← No tiene sentido
GET /pet/123 ← Tiene sentido
GET /pets ← Espera, ¿ahora es plural?
4. Estándares de la Industria
Las principales APIs utilizan nombres plurales:
- API de GitHub:
/repos,/users,/issues - API de Stripe:
/customers,/charges,/subscriptions - API de Twilio:
/accounts,/messages,/calls - APIs de Google:
/users,/groups,/files
Modern PetstoreAPI sigue este estándar con /pets, /orders, /users.
El Modelo Mental de Colección
Entender las colecciones te ayuda a diseñar mejores APIs.
Colecciones en REST
Una colección es un conjunto de recursos. En una API de tienda de mascotas:
/pets- La colección de todas las mascotas/orders- La colección de todos los pedidos/users- La colección de todos los usuarios
Cada colección soporta operaciones:
GET /pets ← Listar mascotas (con filtrado, paginación)
POST /pets ← Crear una nueva mascota
GET /pets/{id} ← Obtener una mascota específica
PUT /pets/{id} ← Actualizar una mascota específica
DELETE /pets/{id} ← Eliminar una mascota específica
Subcolecciones
Las colecciones pueden contener subcolecciones:
GET /pets/{id}/photos ← Colección de fotos para la mascota {id}
POST /pets/{id}/photos ← Añadir foto a la mascota {id}
GET /pets/{id}/photos/{photoId} ← Foto específica
El patrón se mantiene consistente: las colecciones son plurales, los elementos se acceden por ID.
Ejemplo de Modern PetstoreAPI
Modern PetstoreAPI implementa esto correctamente:
GET /pets
GET /pets/{petId}
GET /pets/{petId}/photos
POST /pets/{petId}/vaccinations
GET /orders
GET /orders/{orderId}
GET /orders/{orderId}/items
Cada colección es plural. Cada acceso a un elemento utiliza {id} dentro de esa colección.
Cómo Modern PetstoreAPI Utiliza Nombres Plurales
Veamos ejemplos reales de Modern PetstoreAPI.
Recursos de Mascotas
GET /pets ← Listar todas las mascotas
POST /pets ← Crear una nueva mascota
GET /pets/{petId} ← Obtener mascota específica
PUT /pets/{petId} ← Actualizar mascota
DELETE /pets/{petId} ← Eliminar mascota
GET /pets?status=AVAILABLE ← Filtrar mascotas por estado
Recursos de Pedidos
GET /orders ← Listar todos los pedidos
POST /orders ← Crear pedido
GET /orders/{orderId} ← Obtener pedido específico
PUT /orders/{orderId} ← Actualizar pedido
DELETE /orders/{orderId} ← Cancelar pedido
Recursos de Usuarios
GET /users ← Listar usuarios
POST /users ← Crear usuario
GET /users/{userId} ← Obtener usuario específico
PUT /users/{userId} ← Actualizar usuario
DELETE /users/{userId} ← Eliminar usuario
Recursos Anidados
GET /pets/{petId}/photos ← Fotos de la mascota
POST /pets/{petId}/photos ← Añadir foto
GET /pets/{petId}/vaccinations ← Vacunaciones de la mascota
POST /pets/{petId}/vaccinations ← Registrar vacunación
GET /orders/{orderId}/items ← Ítems del pedido
Consulta la documentación completa de la API REST para ver las listas completas de endpoints.
Argumentos Comunes para el Singular (y Por Qué Están Equivocados)
Abordemos los argumentos comunes para los nombres singulares.
Argumento 1: “La Respuesta es Singular”
Afirmación: “Cuando hago GET /user/123, obtengo un usuario. El singular tiene sentido.”
Contrargumento: La URL representa la ubicación del recurso, no la respuesta. /users/123 significa “elemento 123 en la colección de usuarios.” Que la respuesta sea singular no cambia la estructura de la colección.
Argumento 2: “Se Lee Mejor en el Código”
Afirmación: “getUser(id) se lee mejor que getUsers(id).”
Contrargumento: La nomenclatura de tu código cliente es independiente de la estructura de la URL. Puedes tener:
// URL: GET /users/123
function getUser(id) {
return api.get(`/users/${id}`);
}
El nombre de la función no tiene por qué coincidir con la URL.
Argumento 3: “El Singular Evita Problemas Gramaticales”
Afirmación: “¿Qué pasa con recursos como ‘status’ o ‘information’ que no tienen plurales claros?”
Contrargumento: Estos suelen ser recursos singleton (únicos), no colecciones. Usa el singular para singletons:
GET /status ← Estado del sistema (singleton)
GET /configuration ← Configuración de la aplicación (singleton)
GET /users ← Colección de usuarios (plural)
Estas no son colecciones, por lo que el plural no se aplica.
Argumento 4: “Mi ORM Usa Nombres de Tabla Singulares”
Afirmación: “Mis tablas de base de datos son singulares (user, order), por lo que mi API debería coincidir.”
Contrargumento: El diseño de tu API no debe filtrar detalles de implementación de la base de datos. Las APIs REST representan recursos, no tablas de base de datos. Usa el plural para las colecciones independientemente de tu esquema de base de datos.
Probando la Nomenclatura de Recursos con Apidog
Apidog te ayuda a validar y probar las convenciones de nombres de recursos.
Importar Modern PetstoreAPI
- Importa la especificación OpenAPI de Modern PetstoreAPI
- Apidog detecta automáticamente los patrones de recursos
- Revisa la nomenclatura de los endpoints para asegurar la consistencia
Crear Pruebas de Convenciones de Nombres
// Script de prueba de Apidog
pm.test("Los nombres de los recursos son plurales", function() {
const path = pm.request.url.getPath();
const segments = path.split('/').filter(s => s);
// Comprueba que el primer segmento sea plural
const resource = segments[0];
pm.expect(resource).to.match(/s$/); // Termina en 's'
});
Validar Consistencia
Apidog puede verificar:
- Todos los endpoints de colección usan nombres plurales
- Los subrecursos siguen el mismo patrón
- No hay mezcla de singular/plural en la misma API
Probar con Solicitudes Reales
GET https://api.petstoreapi.com/v1/pets
GET https://api.petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24
GET https://api.petstoreapi.com/v1/orders
Apidog valida las respuestas y te ayuda a asegurar la consistencia de la nomenclatura en toda tu API.
Casos Especiales y Excepciones
Algunos recursos no encajan en el patrón plural.
Recursos Singleton
Los recursos que existen solo una vez deben ser singulares:
GET /status ← Estado del sistema
GET /configuration ← Configuración de la aplicación
GET /health ← Comprobación de salud
GET /metrics ← Métricas del sistema
Estas no son colecciones, por lo que el plural no se aplica.
Recursos de Controlador
Acciones que no encajan en las operaciones CRUD:
POST /login ← Acción de autenticación
POST /logout ← Terminación de sesión
POST /search ← Operación de búsqueda compleja
Estas son excepciones aceptables porque representan acciones, no recursos.
Sustantivos Incontables
Algunos sustantivos no tienen plurales claros:
GET /information ← Singular (incontable)
GET /data ← Singular (incontable)
GET /equipment ← Singular (incontable)
Usa el singular para sustantivos incontables, pero estos son raros en las APIs típicas.
Enfoque de Modern PetstoreAPI
Modern PetstoreAPI maneja estos casos:
# Colecciones (plural)
GET /pets
GET /orders
GET /users
# Singletons (singular)
GET /health
GET /metrics
# Acciones (verbos singulares)
POST /login
POST /logout
Conclusión
Los nombres de recursos de las API REST deben ser plurales. Esto se alinea con la semántica de las colecciones, los métodos HTTP y los estándares de la industria. Modern PetstoreAPI demuestra este patrón correctamente en todos los endpoints.
Puntos clave:
- Usa nombres plurales para las colecciones (
/pets,/orders,/users) - Los elementos individuales se acceden dentro de las colecciones (
/pets/123) - Los recursos singleton pueden ser singulares (
/status,/health) - La consistencia importa más que la perfección
- Prueba tus convenciones de nomenclatura con Apidog
El debate entre plural y singular está zanjado. Sigue el estándar de la industria, usa nombres plurales y construye APIs que los desarrolladores entiendan intuitivamente.
Próximos pasos:
- Revisa los endpoints de tu API para asegurar la consistencia en la nomenclatura
- Consulta la documentación de Modern PetstoreAPI para ver patrones de referencia
- Usa Apidog para validar el diseño de tu API
- Actualiza tu especificación OpenAPI con nombres de recursos plurales
Preguntas Frecuentes
¿Debería cambiar mi API existente de singular a plural?
Si tu API ya está en producción, cambiar los nombres de los recursos es un cambio importante que puede romper la compatibilidad. Considera:
- Añadir nuevos endpoints v2 con nombres plurales
- Mantener la compatibilidad con versiones anteriores mediante redirecciones
- Documentar claramente la convención de nomenclatura
No rompas los clientes existentes solo por la consistencia de la nomenclatura.
¿Qué pasa con los recursos que ya son plurales?
Si el nombre del recurso es naturalmente plural (como “analytics” o “series”), mantenlo tal cual:
GET /analytics ← Ya es plural
GET /series ← Ya es plural
GET /species ← Ya es plural
¿Cómo manejo los recursos anidados?
Mantén ambos niveles en plural:
GET /users/{userId}/orders ← Ambos plurales
GET /pets/{petId}/vaccinations ← Ambos plurales
GET /orders/{orderId}/items ← Ambos plurales
¿Qué pasa si mi equipo prefiere el singular?
La consistencia dentro de tu API es lo más importante. Si tu equipo ya ha estandarizado los nombres singulares y cambiarlo causaría confusión, mantén el singular. Pero para las nuevas APIs, usa el plural.
¿GraphQL usa plural o singular?
GraphQL normalmente usa el singular para consultas de un solo elemento y el plural para listas:
query {
user(id: "123") { ... } # Singular
users(limit: 10) { ... } # Plural
}
Esto es diferente de REST porque las consultas GraphQL son explícitas sobre si devuelven uno o muchos.
¿Cómo maneja esto Modern PetstoreAPI?
Modern PetstoreAPI utiliza nombres plurales consistentemente en todos los endpoints REST. Consulta la guía de la API REST para ver ejemplos completos.
¿Puedo probar las convenciones de nomenclatura automáticamente?
Sí, Apidog puede ejecutar pruebas automatizadas para verificar los patrones de nombres de recursos en toda tu API. Importa tu especificación OpenAPI y crea casos de prueba para las convenciones de nomenclatura.
¿Qué pasa con las APIs que no están en inglés?
La regla del plural se aplica independientemente del idioma. Si tu API utiliza nombres de recursos en francés, usa los plurales en francés. Si usa japonés, sigue las reglas gramaticales japonesas. El principio (las colecciones son plurales) sigue siendo el mismo.