Controllers & Routing

Introduction

Controllers are the front door of your API. Every HTTP request that reaches your Nest application is routed to a method on a controller, which reads the request data, calls the right service and returns a response.

What is a Controller?

A controller is a class decorated with @Controller(). The string you pass becomes a route prefix shared by every method in the class:

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

@Controller('products')
export class ProductsController {
  @Get()
  findAll() {
    return [{ id: 1, name: 'Laptop' }, { id: 2, name: 'Phone' }];
  }
}

When a handler returns an object or array, Nest automatically serializes it to JSON. When it returns a primitive such as a string, Nest sends it as-is.

Route Decorators

Each decorator accepts an optional path that is appended to the controller prefix — @Get('featured') inside @Controller('products') handles GET /products/featured.

Route Parameters

Declare a dynamic segment with a colon, then read it with @Param():

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

@Controller('products')
export class ProductsController {
  @Get(':id')
  findOne(@Param('id') id: string) {
    return `Product #${id}`;
  }
}

Query Parameters

@Get()
findAll(@Query('category') category?: string, @Query('page') page = '1') {
  return { category, page };
}

Request Body

Use @Body() to read the JSON body of POST, PUT and PATCH requests. The standard Nest approach is to describe the expected shape with a DTO (Data Transfer Object) class:

// src/products/dto/create-product.dto.ts
export class CreateProductDto {
  name: string;
  price: number;
}

// src/products/products.controller.ts
@Post()
create(@Body() createProductDto: CreateProductDto) {
  return { message: 'Product created', product: createProductDto };
}

Why a class rather than an interface? TypeScript interfaces disappear when code is compiled, but classes still exist at runtime — which lets Nest validate incoming data against them, as you will see in lesson 6.

A Complete CRUD Controller

import {
  Body, Controller, Delete, Get, Param, ParseIntPipe, Patch, Post,
} from '@nestjs/common';
import { ProductsService } from './products.service.js';
import { CreateProductDto } from './dto/create-product.dto.js';
import { UpdateProductDto } from './dto/update-product.dto.js';

@Controller('products')
export class ProductsController {
  constructor(private readonly productsService: ProductsService) {}

  @Post()
  create(@Body() dto: CreateProductDto) {
    return this.productsService.create(dto);
  }

  @Get()
  findAll() {
    return this.productsService.findAll();
  }

  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    return this.productsService.findOne(id);
  }

  @Patch(':id')
  update(@Param('id', ParseIntPipe) id: number, @Body() dto: UpdateProductDto) {
    return this.productsService.update(id, dto);
  }

  @Delete(':id')
  remove(@Param('id', ParseIntPipe) id: number) {
    return this.productsService.remove(id);
  }
}

Notice the controller contains no business logic at all — it only reads request data and delegates to ProductsService. You will write that service in the next lesson.

Status Codes & Headers

By default Nest responds with 200 OK, except POST handlers, which respond with 201 Created. Override this with @HttpCode(), and add response headers with @Header():

import { Delete, Header, HttpCode, HttpStatus, Param } from '@nestjs/common';

@Delete(':id')
@HttpCode(HttpStatus.NO_CONTENT) // 204
remove(@Param('id') id: string) {
  // delete the product...
}

@Get('export')
@Header('Cache-Control', 'no-store')
exportAll() {
  return [];
}

Async Handlers

Real handlers usually wait on a database or another API. Nest fully supports async handlers — just return a Promise (or an RxJS Observable) and Nest resolves it before sending the response:

@Get()
async findAll(): Promise<Product[]> {
  return this.productsService.findAll();
}

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

You can now build complete REST endpoints with Nest controllers. The controller you wrote delegates to a ProductsService — next, you will learn how providers work and how Nest's dependency injection creates and delivers them automatically.