Controllers in NestJS

This chapter follows Modules in NestJS.

A controller is the part of a Nest application that knows about HTTP. It declares which paths and methods it answers, pulls the pieces it needs out of the request, calls a provider, and returns a value. Nest turns that value into the response. Keeping controllers that thin is the point: the logic lives in providers, which can be tested and reused without a request object.

Routes from decorators

@Controller('cats') sets a path prefix, and a method decorator per HTTP verb adds the rest. The method name does not matter to routing.

1
import { Body, Controller, Delete, Get, HttpCode, Param, ParseIntPipe, Patch, Post, Query } from '@nestjs/common';
2
import { CatsService } from './cats.service';
3
import { CreateCatDto } from './dto/create-cat.dto';
4
import { UpdateCatDto } from './dto/update-cat.dto';
5

6
@Controller('cats')
7
export class CatsController {
8
  constructor(private readonly catsService: CatsService) {}
9

10
  @Get()
11
  findAll(@Query('breed') breed?: string) {
12
    return this.catsService.findAll({ breed });
13
  }
14

15
  @Get(':id')
16
  findOne(@Param('id', ParseIntPipe) id: number) {
17
    return this.catsService.findOne(id);
18
  }
19

20
  @Post()
21
  create(@Body() dto: CreateCatDto) {
22
    return this.catsService.create(dto);
23
  }
24

25
  @Patch(':id')
26
  update(@Param('id', ParseIntPipe) id: number, @Body() dto: UpdateCatDto) {
27
    return this.catsService.update(id, dto);
28
  }
29

30
  @Delete(':id')
31
  @HttpCode(204)
32
  remove(@Param('id', ParseIntPipe) id: number) {
33
    return this.catsService.remove(id);
34
  }
35
}

This gives GET /cats, GET /cats/:id, POST /cats, PATCH /cats/:id, and DELETE /cats/:id. A controller only serves requests once it is listed in the controllers array of a module. nest g resource cats generates this whole shape, including the module, service, and DTOs.

Reading the request

Parameter decorators pull one part of the request into a method argument:

Every value from the URL arrives as a string. ParseIntPipe in @Param('id', ParseIntPipe) converts it to a number, or rejects the request with 400 Bad Request if it is not numeric. Pipes are covered in Pipes and validation in NestJS.

Request bodies and DTOs

A data transfer object is a class that describes the shape of a body. It is a class, not an interface, because classes still exist at runtime, which lets Nest validate the body against the decorators on it.

1
import { IsInt, IsString, Min } from 'class-validator';
2

3
export class CreateCatDto {
4
  @IsString()
5
  name: string;
6

7
  @IsInt()
8
  @Min(0)
9
  age: number;
10

11
  @IsString()
12
  breed: string;
13
}

An update DTO usually makes every field optional. PartialType from @nestjs/mapped-types derives it without repeating the fields, and it keeps the validation rules:

1
import { PartialType } from '@nestjs/mapped-types';
2
import { CreateCatDto } from './create-cat.dto';
3

4
export class UpdateCatDto extends PartialType(CreateCatDto) {}

The DTO describes the HTTP contract. It does not have to match the database document. When the two drift apart, keep a separate type for what the service stores and map between them in the service.

Status codes, headers, and redirects

A handler’s return value becomes the body. Objects and arrays are serialized to JSON, and a returned Promise or RxJS Observable is awaited first. The status code is 200, except for POST, which defaults to 201. Decorators change the defaults:

1
@Post('import')
2
@HttpCode(202)
3
@Header('Cache-Control', 'no-store')
4
startImport() {
5
  return this.catsService.startImport();
6
}
7

8
@Get('docs')
9
@Redirect('https://docs.nestjs.com', 302)
10
docs() {}

Errors are thrown, not returned. throw new NotFoundException() produces a 404 with a JSON body. Exception filters in NestJS covers the full set.

The library-specific response

@Res() injects the Express (or Fastify) response object. Once you inject it, Nest stops sending the response for you, and the handler must call res.send() or res.json() itself. That also bypasses interceptors that transform the return value.

1
import type { Response } from 'express';
2

3
@Get('export')
4
export(@Res({ passthrough: true }) res: Response) {
5
  res.setHeader('Content-Disposition', 'attachment; filename="cats.json"');
6
  return this.catsService.findAll({});
7
}

passthrough: true is the middle ground: the handler can set a cookie or a header on the native object and still return a value that Nest serializes. Use the native object only for what the decorators cannot express, such as streaming a file, because it ties the controller to one platform adapter.

Next: Providers and dependency injection in NestJS.