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