NestJS Route Parameters

Extracting a Single Route Parameter

Declare a dynamic segment in the route path with a leading colon, then extract its value in the handler using @Param('name'). Route parameter values always arrive as strings, even when they look numeric.

import { Controller, Get, Param } from '@nestjs/common';

@Controller('cats')
export class CatsController {
  @Get(':id')
  findOne(@Param('id') id: string) {
    return `Cat with id ${id}`;
  }
}

Even though id looks like a number in the URL, @Param('id') always returns a string, you must convert it explicitly (or use a pipe) if you need a number.

Extracting All Parameters at Once

@Get(':userId/orders/:orderId')
findOrder(@Param() params: { userId: string; orderId: string }) {
  return params;
}

• @Param('name') extracts a single named parameter as a string.
• @Param() with no argument returns an object containing every route parameter.
• Combine @Param('id', ParseIntPipe) to automatically convert and validate the value as a number.
• Route parameter names must exactly match the colon-prefixed name in the route path.

@Param Cheatsheet

Common ways to extract route parameters.

Converting Parameter Types With Pipes

Because route parameters always arrive as strings, Nest ships built-in pipes like ParseIntPipe, ParseBoolPipe, and ParseUUIDPipe that convert and validate a parameter's value in one step, throwing a 400 Bad Request automatically if conversion fails.

@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {
  // id is guaranteed to be a valid number here
  return this.catsService.findOne(id);
}

Working With Multiple Parameters

Nested resources often need more than one parameter, like a specific order belonging to a specific user. Each colon-prefixed segment becomes its own named parameter, extracted individually or together.

• /users/:userId/orders/:orderId exposes both userId and orderId.
• Extract them individually for clarity, or as a single object when passing them straight through.
• Validate that the referenced parent resource (userId) actually exists before trusting the child lookup.

Common Mistakes

• Forgetting route parameters are always strings and comparing them to numbers with ===.
• Mismatching the name passed to @Param() with the name declared in the route path.
• Not validating that a numeric-looking parameter is actually a valid number before using it in a query.
• Extracting every parameter with @Param() when only one is actually needed, hurting readability.

Key Takeaways

• Route parameters are declared with a colon in the path and extracted with @Param().
• Parameter values are always strings unless converted, typically with a pipe like ParseIntPipe.
• @Param() without an argument returns all parameters as one object.
• Built-in parsing pipes both convert and validate parameters in a single step.