Uno de los aspectos más visibles y determinantes en una API REST es cómo nombras tus endpoints y recursos. Aunque puede parecer algo menor, una mala convención puede llevar a confusión, errores de integración, o incluso a violar principios de diseño RESTful.
Este artículo te enseña las mejores prácticas y convenciones de naming para crear APIs más limpias, consistentes y mantenibles.
¿Qué es un recurso en REST?
En REST, los datos o entidades que se exponen a través de una API se llaman recursos. Un recurso puede ser:
- Una entidad (ej. un usuario, producto, factura)
- Una colección de entidades
- Una relación entre recursos (comentarios de un post, productos de una orden)
Cada recurso se representa mediante una URL única.
Principios fundamentales para nombrar endpoints REST
Antes de definir los endpoints de una API REST, es fundamental entender que REST se basa en el concepto de recursos, no de acciones. Por eso, las rutas deben representar entidades del negocio (como usuarios, productos o pedidos) y no funciones o comandos.
Usar sustantivos en lugar de verbos, por ejemplo /usuarios en vez de /obtenerUsuarios, permite que la semántica del verbo HTTP (como GET, POST, PUT) sea quien indique la acción que se está realizando.
Del mismo modo, los recursos deben nombrarse en plural para indicar que se trata de una colección (/clientes, /facturas), mientras que un identificador en la ruta (/clientes/123) señala una entidad específica.
Además, cuando hay relaciones jerárquicas entre recursos (por ejemplo, compras hechas por un usuario), es válido usar un anidamiento moderado como /usuarios/42/compras, siempre que se mantenga la claridad y no se generen rutas excesivamente profundas. Estas convenciones ayudan a construir APIs más predecibles, consistentes y fáciles de consumir.
Usa sustantivos, no verbos
GET /usuarios, no GET /obtenerUsuarios
POST /facturas, no POST /crearFactura
Nombres en plural para colecciones
GET /clientes
POST /pedidos
Refleja que estás accediendo a un conjunto de recursos
Identificadores como parte de la URL
GET /clientes/123
PUT /productos/456
El ID representa un único recurso
Anida relaciones jerárquicas con cuidado
GET /usuarios/42/compras → todas las compras del usuario 42
GET /ordenes/99/productos → productos en una orden específica
Evita profundidad innecesaria
Mal: /sistema/usuarios/listado/activos
Bien: /usuarios?estado=activo
Verbos HTTP y su uso esperado
Los verbos HTTP son la forma en que indicamos la acción que queremos realizar sobre un recurso en una API REST.
Cada verbo tiene un propósito específico y, cuando se usan correctamente, ayudan a que la API sea más clara, coherente y fácil de consumir.
Por ejemplo, GET se usa para obtener datos, POST para crear nuevos recursos, PUT para reemplazar completamente un recurso existente, PATCH para modificarlo parcialmente, y DELETE para eliminarlo.
La clave está en que la acción está en el verbo HTTP, no en la URL, por eso no se recomienda usar rutas como /crearUsuario o /eliminarProducto, ya que duplican la semántica.
Usar los verbos correctamente permite a quienes consumen la API entender de inmediato qué hace cada endpoint, seguir estándares universales y facilitar la integración con herramientas y frameworks que ya esperan este comportamiento.
| Verbo | Propósito | Ejemplo |
|---|---|---|
| GET | Obtener datos | GET /usuarios |
| POST | Crear un nuevo recurso | POST /usuarios |
| PUT | Reemplazar un recurso existente | PUT /usuarios/123 |
| PATCH | Modificar parcialmente un recurso | PATCH /usuarios/123 |
| DELETE | Eliminar un recurso | DELETE /usuarios/123 |
❗ No pongas el verbo en la URL. El verbo ya está en el método HTTP.
Cómo nombrar acciones no CRUD
Aunque las APIs REST están pensadas para operar sobre recursos con acciones estándar como crear (POST), leer (GET), actualizar (PUT/PATCH) y eliminar (DELETE) —es decir, operaciones CRUD—, en la práctica muchas veces surgen necesidades que no encajan directamente en ese modelo.
Por ejemplo: activar un usuario, cancelar una orden o marcar una tarea como completada. Estas acciones no CRUD deben representarse con cuidado para no romper la consistencia REST.
Una práctica común es usar subrecursos o rutas de acción claras, como POST /usuarios/42/activar o POST /ordenes/88/cancelaciones, que permiten expresar operaciones específicas sobre un recurso sin abusar de verbos en la URL.
Aunque no son estrictamente RESTful, estas convenciones son aceptadas ampliamente y mantienen la claridad sin sacrificar expresividad, siempre y cuando no se utilicen en exceso ni se conviertan en la norma para toda la API.
Opciones recomendadas:
Subrecurso con verbo como sustantivo
POST /usuarios/42/activaciones → activa al usuario 42
POST /ordenes/88/cancelaciones → cancela la orden 88
Ruta de acción clara
POST /usuarios/42/activar
POST /ordenes/88/marcar-como-pagada
No abuses de estas rutas: si tu API tiene muchas acciones "verbales", puede indicar que necesitas rediseñar los recursos.
Convenciones para filtros, paginación y ordenamiento
En APIs REST, es común que los consumidores necesiten filtrar resultados, ordenarlos o paginarlos cuando trabajan con colecciones grandes de recursos. Para eso, existen convenciones ampliamente aceptadas que permiten hacerlo de forma clara y predecible.
Por ejemplo, los filtros suelen aplicarse como parámetros de query (GET /productos?categoria=ropa&stock=disponible), lo que permite al cliente obtener solo los recursos que cumplan ciertos criterios. Para la paginación, se usan parámetros como page y limit (GET /clientes?page=2&limit=10), que indican la página deseada y la cantidad de elementos por página.
Y para el ordenamiento, es común usar un parámetro sort (GET /articulos?sort=-fecha) donde un prefijo - indica orden descendente. Estas convenciones facilitan el consumo de la API desde interfaces gráficas, reportes, dashboards u otros sistemas, y son compatibles con librerías frontend y motores de búsqueda ampliamente utilizados.
Filtros:
GET /productos?categoria=ropa&stock=disponible
Paginación:
GET /clientes?page=2&limit=20
Ordenamiento:
GET /articulos?sort=-fecha
Usa
-campopara orden descendente. Esto es compatible con muchas librerías frontend.
Convenciones para respuestas anidadas
GET /ordenes/10/productos
→ Lista todos los productos de la orden 10.
GET /usuarios/5/compras/17
→ Obtiene una compra específica del usuario 5.
Evita hacer anidamientos innecesarios si los recursos no dependen jerárquicamente.
Nombres comunes para endpoints útiles
| Endpoint | Descripción |
|---|---|
/me |
Información del usuario autenticado |
/status o /health |
Estado general del sistema (monitoring) |
/login, /logout |
Autenticación básica |
/search |
Búsqueda avanzada o global |
/webhooks |
Endpoints de integración con terceros |
Qué evitar
❌ /getAllUsers, /createInvoice → no uses verbos en la ruta
❌ /api/v1/v1/usuarios → no repitas versión o prefijos innecesarios
❌ /cliente/123/factura/1/detalle/4/campo/5 → evita profundidad excesiva
❌ /users?id=123 → si el ID está en el query, usa mejor /users/123
Usa kebab-case o snake_case en los parámetros y camelCase en los campos del JSON
En las URLs y parámetros de query, se recomienda usar kebab-case (campo-con-guiones) o snake_case (campo_con_guion_bajo), ya que son más legibles y compatibles con navegadores y herramientas CLI.
En el cuerpo del JSON (request o response), se recomienda usar camelCase, que es el estándar en JavaScript y la mayoría de lenguajes frontend.
Ejemplo correcto:
GET /usuarios?ordenar-por=fecha_registro
JSON de respuesta:
{
"id": 123,
"nombreCompleto": "Javier Padrón",
"correoElectronico": "javier@example.com"
}
Evita mezclar estilos en el mismo lugar (por ejemplo, no uses snake_case en el JSON si tu equipo usa camelCase).
Usa un idioma consistente en toda tu API
Elegir un idioma para tu API (español o inglés) y mantenerlo consistente es crucial para evitar confusión y errores.
Evita mezclar esto:
GET /clientes?status=active
Mejor opción:
GET /clientes?estado=activo
O bien, todo en inglés:
GET /customers?status=active
Lo importante no es el idioma en sí, sino que toda la API hable el mismo lenguaje, desde los endpoints hasta los nombres de campos y errores.
Conclusión
Nombrar bien los endpoints y recursos REST no es una cuestión estética: es una práctica esencial para construir APIs que sean claras, predecibles, fáciles de documentar y de usar por otros equipos.
Sigue estas convenciones y estarás facilitando la vida a todos quienes consumen tu API: desde frontends, apps móviles, hasta integradores externos.
