1---
2title: Use API Versioning for Breaking Changes
3impact: MEDIUM
4impactDescription: Versioning allows you to evolve APIs without breaking existing clients
5tags: api, versioning, breaking-changes, compatibility
6---
7 
8## Use API Versioning for Breaking Changes
9 
10Use NestJS built-in versioning when making breaking changes to your API. Choose a versioning strategy (URI, header, or media type) and apply it consistently. This allows old clients to continue working while new clients use updated endpoints.
11 
12**Incorrect (breaking changes without versioning):**
13 
14```typescript
15// Breaking changes without versioning
16@Controller('users')
17export class UsersController {
18  @Get(':id')
19  async findOne(@Param('id') id: string): Promise<User> {
20    // Original response: { id, name, email }
21    // Later changed to: { id, firstName, lastName, emailAddress }
22    // Old clients break!
23    return this.usersService.findOne(id);
24  }
25}
26 
27// Manual versioning in routes
28@Controller('v1/users')
29export class UsersV1Controller {}
30 
31@Controller('v2/users')
32export class UsersV2Controller {}
33// Inconsistent, error-prone, hard to maintain
34```
35 
36**Correct (use NestJS built-in versioning):**
37 
38```typescript
39// Enable versioning in main.ts
40async function bootstrap() {
41  const app = await NestFactory.create(AppModule);
42 
43  // URI versioning: /v1/users, /v2/users
44  app.enableVersioning({
45    type: VersioningType.URI,
46    defaultVersion: '1',
47  });
48 
49  // Or header versioning: X-API-Version: 1
50  app.enableVersioning({
51    type: VersioningType.HEADER,
52    header: 'X-API-Version',
53    defaultVersion: '1',
54  });
55 
56  // Or media type: Accept: application/json;v=1
57  app.enableVersioning({
58    type: VersioningType.MEDIA_TYPE,
59    key: 'v=',
60    defaultVersion: '1',
61  });
62 
63  await app.listen(3000);
64}
65 
66// Version-specific controllers
67@Controller('users')
68@Version('1')
69export class UsersV1Controller {
70  @Get(':id')
71  async findOne(@Param('id') id: string): Promise<UserV1Response> {
72    const user = await this.usersService.findOne(id);
73    // V1 response format
74    return {
75      id: user.id,
76      name: user.name,
77      email: user.email,
78    };
79  }
80}
81 
82@Controller('users')
83@Version('2')
84export class UsersV2Controller {
85  @Get(':id')
86  async findOne(@Param('id') id: string): Promise<UserV2Response> {
87    const user = await this.usersService.findOne(id);
88    // V2 response format with breaking changes
89    return {
90      id: user.id,
91      firstName: user.firstName,
92      lastName: user.lastName,
93      emailAddress: user.email,
94      createdAt: user.createdAt,
95    };
96  }
97}
98 
99// Per-route versioning - different versions for different routes
100@Controller('users')
101export class UsersController {
102  @Get()
103  @Version('1')
104  findAllV1(): Promise<UserV1Response[]> {
105    return this.usersService.findAllV1();
106  }
107 
108  @Get()
109  @Version('2')
110  findAllV2(): Promise<UserV2Response[]> {
111    return this.usersService.findAllV2();
112  }
113 
114  @Get(':id')
115  @Version(['1', '2']) // Same handler for multiple versions
116  findOne(@Param('id') id: string): Promise<User> {
117    return this.usersService.findOne(id);
118  }
119 
120  @Post()
121  @Version(VERSION_NEUTRAL) // Available in all versions
122  create(@Body() dto: CreateUserDto): Promise<User> {
123    return this.usersService.create(dto);
124  }
125}
126 
127// Shared service with version-specific logic
128@Injectable()
129export class UsersService {
130  async findOne(id: string, version: string): Promise<any> {
131    const user = await this.repo.findOne({ where: { id } });
132 
133    if (version === '1') {
134      return this.toV1Response(user);
135    }
136    return this.toV2Response(user);
137  }
138 
139  private toV1Response(user: User): UserV1Response {
140    return {
141      id: user.id,
142      name: `${user.firstName} ${user.lastName}`,
143      email: user.email,
144    };
145  }
146 
147  private toV2Response(user: User): UserV2Response {
148    return {
149      id: user.id,
150      firstName: user.firstName,
151      lastName: user.lastName,
152      emailAddress: user.email,
153      createdAt: user.createdAt,
154    };
155  }
156}
157 
158// Controller extracts version
159@Controller('users')
160export class UsersController {
161  @Get(':id')
162  async findOne(
163    @Param('id') id: string,
164    @Headers('X-API-Version') version: string = '1',
165  ): Promise<any> {
166    return this.usersService.findOne(id, version);
167  }
168}
169 
170// Deprecation strategy - mark old versions as deprecated
171@Controller('users')
172@Version('1')
173@UseInterceptors(DeprecationInterceptor)
174export class UsersV1Controller {
175  // All V1 routes will include deprecation warning
176}
177 
178@Injectable()
179export class DeprecationInterceptor implements NestInterceptor {
180  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
181    const response = context.switchToHttp().getResponse();
182    response.setHeader('Deprecation', 'true');
183    response.setHeader('Sunset', 'Sat, 1 Jan 2025 00:00:00 GMT');
184    response.setHeader('Link', '</v2/users>; rel="successor-version"');
185 
186    return next.handle();
187  }
188}
189```
190 
191Reference: [NestJS Versioning](https://docs.nestjs.com/techniques/versioning)
192