NestJS API Versioning

Enabling Versioning

NestJS supports four versioning strategies out of the box: URI-based (/v1/cats), header-based, media-type-based, and custom. Versioning is enabled once at the application level, then applied per-controller or per-route.

import { VersioningType } from '@nestjs/common';

const app = await NestFactory.create(AppModule);
app.enableVersioning({
  type: VersioningType.URI,
  defaultVersion: '1',
});
await app.listen(3000);

With URI versioning enabled, a controller version of '2' automatically becomes reachable at /v2/..., while unspecified controllers default to /v1/....

Versioning a Controller or Route

@Controller({ path: 'cats', version: '2' })
export class CatsControllerV2 {}

@Controller('cats')
export class CatsController {
  @Version('2')
  @Get()
  findAllV2() {}
}

• version can be set on the whole controller or on individual routes.
• VERSION_NEUTRAL marks a route as available under every version.
• URI versioning is the most explicit and cache-friendly strategy for public APIs.
• Header and media-type versioning keep URLs stable but require documenting a custom header or Accept value.

Versioning Strategy Cheatsheet

The four versioning types NestJS supports out of the box.

When You Actually Need Versioning

Not every change requires a new version. Additive, backward-compatible changes (new optional fields, new endpoints) don't need one. Reserve versioning for genuinely breaking changes: removing a field, changing a field's type, or altering response structure that existing clients depend on.

• Adding a new optional response field: no version bump needed.
• Renaming or removing an existing field: needs a new version.
• Changing an endpoint's URL structure entirely: needs a new version.
• Fixing an actual bug in existing behavior: usually not a version bump, it's a bug fix.

Maintaining Multiple Versions Cleanly

Rather than branching logic with conditionals inside one controller, keep separate versioned controllers that share a common service layer, only the request/response mapping differs between versions, not the underlying business logic.

Common Mistakes

• Introducing a new API version for a purely additive, non-breaking change.
• Duplicating business logic across versioned controllers instead of sharing one service layer.
• Never deprecating or removing old versions, leaving an ever-growing surface to maintain.
• Choosing header-based versioning for a public API without documenting the required header clearly.

Key Takeaways

• NestJS supports URI, header, media-type, and custom versioning strategies.
• Versioning can be applied at the controller level or the individual route level.
• Reserve new versions for genuinely breaking changes, not additive ones.
• Share a common service layer across versioned controllers to avoid duplicated logic.