Construir una API profesional implica mucho más que definir rutas estáticas. La verdadera potencia aparece cuando tus endpoints pueden recibir parámetros dinámicos para consultar recursos específicos, como un producto por su ID o las tareas de un usuario concreto. A continuación se explica paso a paso cómo lograrlo en NestJS utilizando el decorador @Param.
¿Por qué necesitas parámetros en tus rutas REST?
Cuando diseñas una REST API, cada recurso suele tener su propia ruta en plural —/tasks, /people, /users—. Un pequeño tip de buenas prácticas: siempre nombra tus endpoints en plural [0:18].
Pero el escenario real es que necesitas acceder a un recurso individual. Por ejemplo:
/tasks/1 → obtener la tarea con ID 1./people/5 → obtener la persona con ID 5./users/1/tasks → obtener las tareas del usuario 1.
Este último caso muestra cómo puedes anidar rutas para representar relaciones entre recursos, lo que resulta fundamental para mantener una API clara y predecible [0:30].
¿Cómo se define un parámetro dinámico en el controlador?
En NestJS, la forma de declarar un parámetro dentro de la ruta es con dos puntos seguidos del nombre: :id. Luego, para recibirlo dentro del método, se usa el decorador @Param, que se importa del mismo paquete que @Get [1:10].
Recibir todos los parámetros como objeto
La primera forma consiste en capturar el objeto completo de parámetros:
typescript
@Get('products/:id')
getProduct(@Param() params: any) {
return Producto con id ${params.id};
}
Aquí, params es un objeto y accedes al valor con params.id. El nombre que uses después de los dos puntos en la ruta —:id— es exactamente la propiedad que debes consultar en el objeto. Si lo llamas :productId, entonces sería params.productId [2:05].
Al probar en el navegador, la ruta /products sin parámetro devuelve un error 404 porque esa ruta no está definida. Solo /products/1 o /products/abc123 funcionan, ya que coinciden con el parámetro dinámico [2:40].
Recibir un parámetro específico con tipado
Existe una forma más directa: indicarle a @Param qué parámetro concreto quieres resolver [3:20].
typescript
@Get('products/:id')
getProduct(@Param('id') id: string) {
return Producto con id ${id};
}
De esta manera ya no necesitas hacer params.id; recibes el valor directamente y puedes tiparlo como string o number desde el inicio. Los identificadores pueden llegar como números en bases de datos relacionales o como cadenas alfanuméricas en bases de datos no relacionales [3:00].
¿Cómo manejar múltiples parámetros en una sola ruta?
Hay escenarios donde una ruta necesita dos o más parámetros. Por ejemplo, obtener un producto específico dentro de una categoría:
typescript
@Get('categories/:id/products/:productId')
getCategoryProduct(
@Param('id') id: string,
@Param('productId') productId: string,
) {
return Categoría ${id}, Producto ${productId};
}
Simplemente repites el decorador @Param por cada valor que necesites extraer de la ruta [4:15]. Si la línea se vuelve demasiado larga, puedes aplicar un formatter de código para mantener la legibilidad.
Probando la ruta con dos parámetros
Al visitar /categories/10/products/, el servidor responde con 404 porque falta el segundo parámetro. Al completar la URL —/categories/10/products/25— ambos valores se reciben correctamente [5:10].
Puntos clave para recordar:
- El nombre del parámetro en la ruta (
:id, :productId) debe coincidir con el nombre dentro de @Param('...').
- Puedes combinar tantos parámetros como necesite tu ruta.
- Tipar los parámetros desde la firma del método ayuda a prevenir errores.
Ahora que dominas los parámetros de ruta, el siguiente paso natural son los parámetros de tipo query, que permiten filtrar, paginar y ordenar resultados. ¿Ya tienes ideas de cómo estructurarías tus rutas? Comparte tu enfoque en los comentarios.
