nestjs-api-standards

name	nestjs-api-standards
description	Create standardized API response envelopes, paginated endpoints, and error interceptors in NestJS. Use when implementing response wrappers, pagination DTOs, or global error formats.
license	MIT
version	1.0.0
author	[Filippo De Silva](https://github.com/FilippoDeSilva)
tags	["nestjs","api","response","pagination","error"]
metadata	{"triggers":{"files":["**/*.controller.ts","**/*.dto.ts"],"keywords":["ApiResponse","Pagination","TransformInterceptor"]}}

NestJS API Standards & Common Patterns

Priority: P1 (OPERATIONAL)

Workflow: Standardize API Endpoint

1. Create Response DTO — Define dedicated DTO for every endpoint return type.
2. Map entity to DTO — Use plainToInstance(UserResponseDto, user) in service or controller.
3. Apply TransformInterceptor — Bind globally to wrap all responses in { statusCode, data, meta }.
4. Add nested validation — Decorate nested DTO properties with @ValidateNested() + @Type().
5. Document with Swagger — Apply @ApiResponse({ status, type }) with exact types per endpoint.

Response Wrapper Example

See implementation examples

Entity-to-DTO Mapping Example

See implementation examples

Deep Validation (Critical)

• [Rule] Nested Validation: Object/array DTO properties require @ValidateNested() + @Type(() => TargetDto) from class-transformer.

Pagination Standards

• DTOs: Use strict PageOptionsDto (page/take/order) and PageDto<T> (data/meta).
• Swagger Logic: Generics require ApiExtraModels and schema path resolution.
• Reference: See Pagination Wrapper Implementation for complete ApiPaginatedResponse decorator code.

Custom Error Response

• Standard Error Object: Define ApiErrorResponse with statusCode, message, error, timestamp, path. See Error Response Class.
• Docs: Apply @ApiBadRequestResponse({ type: ApiErrorResponse }) globally or per controller.

Anti-Patterns

• No raw entity returns: Always map to Response DTO; raw entities leak internal fields.
• No unvalidated nested DTOs: Use @ValidateNested() + @Type() for all nested object properties.
• No generic 200 docs: Apply @ApiResponse({ status, type }) with exact types per endpoint.

References

• Pagination Wrapper
• Error Response Class