1---
2title: Use DTOs and Serialization for API Responses
3impact: MEDIUM
4impactDescription: Response DTOs prevent accidental data exposure and ensure consistency
5tags: api, dto, serialization, class-transformer
6---
7 
8## Use DTOs and Serialization for API Responses
9 
10Never return entity objects directly from controllers. Use response DTOs with class-transformer's `@Exclude()` and `@Expose()` decorators to control exactly what data is sent to clients. This prevents accidental exposure of sensitive fields and provides a stable API contract.
11 
12**Incorrect (returning entities directly or manual spreading):**
13 
14```typescript
15// Return entities directly
16@Controller('users')
17export class UsersController {
18  @Get(':id')
19  async findOne(@Param('id') id: string): Promise<User> {
20    return this.usersService.findById(id);
21    // Returns: { id, email, passwordHash, ssn, internalNotes, ... }
22    // Exposes sensitive data!
23  }
24}
25 
26// Manual object spreading (error-prone)
27@Get(':id')
28async findOne(@Param('id') id: string) {
29  const user = await this.usersService.findById(id);
30  return {
31    id: user.id,
32    email: user.email,
33    name: user.name,
34    // Easy to forget to exclude sensitive fields
35    // Hard to maintain across endpoints
36  };
37}
38```
39 
40**Correct (use class-transformer with @Exclude and response DTOs):**
41 
42```typescript
43// Enable class-transformer globally
44async function bootstrap() {
45  const app = await NestFactory.create(AppModule);
46  app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
47  await app.listen(3000);
48}
49 
50// Entity with serialization control
51@Entity()
52export class User {
53  @PrimaryGeneratedColumn('uuid')
54  id: string;
55 
56  @Column()
57  email: string;
58 
59  @Column()
60  name: string;
61 
62  @Column()
63  @Exclude() // Never include in responses
64  passwordHash: string;
65 
66  @Column({ nullable: true })
67  @Exclude()
68  ssn: string;
69 
70  @Column({ default: false })
71  @Exclude({ toPlainOnly: true }) // Exclude from response, allow in requests
72  isAdmin: boolean;
73 
74  @CreateDateColumn()
75  createdAt: Date;
76 
77  @Column()
78  @Exclude()
79  internalNotes: string;
80}
81 
82// Now returning entity is safe
83@Controller('users')
84export class UsersController {
85  @Get(':id')
86  async findOne(@Param('id') id: string): Promise<User> {
87    return this.usersService.findById(id);
88    // Returns: { id, email, name, createdAt }
89    // Sensitive fields excluded automatically
90  }
91}
92 
93// For different response shapes, use explicit DTOs
94export class UserResponseDto {
95  @Expose()
96  id: string;
97 
98  @Expose()
99  email: string;
100 
101  @Expose()
102  name: string;
103 
104  @Expose()
105  @Transform(({ obj }) => obj.posts?.length || 0)
106  postCount: number;
107 
108  constructor(partial: Partial<User>) {
109    Object.assign(this, partial);
110  }
111}
112 
113export class UserDetailResponseDto extends UserResponseDto {
114  @Expose()
115  createdAt: Date;
116 
117  @Expose()
118  @Type(() => PostResponseDto)
119  posts: PostResponseDto[];
120}
121 
122// Controller with explicit DTOs
123@Controller('users')
124export class UsersController {
125  @Get()
126  @SerializeOptions({ type: UserResponseDto })
127  async findAll(): Promise<UserResponseDto[]> {
128    const users = await this.usersService.findAll();
129    return users.map(u => plainToInstance(UserResponseDto, u));
130  }
131 
132  @Get(':id')
133  async findOne(@Param('id') id: string): Promise<UserDetailResponseDto> {
134    const user = await this.usersService.findByIdWithPosts(id);
135    return plainToInstance(UserDetailResponseDto, user, {
136      excludeExtraneousValues: true,
137    });
138  }
139}
140 
141// Groups for conditional serialization
142export class UserDto {
143  @Expose()
144  id: string;
145 
146  @Expose()
147  name: string;
148 
149  @Expose({ groups: ['admin'] })
150  email: string;
151 
152  @Expose({ groups: ['admin'] })
153  createdAt: Date;
154 
155  @Expose({ groups: ['admin', 'owner'] })
156  settings: UserSettings;
157}
158 
159@Controller('users')
160export class UsersController {
161  @Get()
162  @SerializeOptions({ groups: ['public'] })
163  async findAllPublic(): Promise<UserDto[]> {
164    // Returns: { id, name }
165  }
166 
167  @Get('admin')
168  @UseGuards(AdminGuard)
169  @SerializeOptions({ groups: ['admin'] })
170  async findAllAdmin(): Promise<UserDto[]> {
171    // Returns: { id, name, email, createdAt }
172  }
173 
174  @Get('me')
175  @SerializeOptions({ groups: ['owner'] })
176  async getProfile(@CurrentUser() user: User): Promise<UserDto> {
177    // Returns: { id, name, settings }
178  }
179}
180```
181 
182Reference: [NestJS Serialization](https://docs.nestjs.com/techniques/serialization)
183