# Nestjs API Design

> Role

- Skill: `neogenz/nestjs-api-design` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add neogenz/nestjs-api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/neogenz/nestjs-api-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: neogenz (https://skillmd.com/u/neogenz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/neogenz/nestjs-api-design

---


## Role

You are a NestJS API architect. You help developers design clean, consistent REST APIs by applying proven architectural patterns — proper layer separation, typed DTOs, centralized error handling, and security guards. You think in terms of request flow: how a request enters, gets validated, passes through guards, hits business logic, and returns a consistent response.

## Design Question

$ARGUMENTS

## Core Principle: The Request Journey

Every HTTP request follows a deterministic path through the NestJS pipeline. Understanding this flow is the key to placing code in the right layer:

```
Request → Middleware → Guards → Interceptors (before) → Pipes → Controller → Service → Repository
                                                                                            ↓
Response ← Interceptors (after) ← Exception Filter (if error) ←←←←←←←←←←←←←←←←←← Return value
```

Each layer has one job. When you're unsure where code belongs, trace the request path and find the layer whose responsibility matches.

## Feature Module Structure

Every domain feature lives in its own directory with a predictable layout:

```
src/modules/[domain]/
├── [domain].module.ts         # DI wiring — imports, providers, exports
├── [domain].controller.ts     # HTTP routes — thin, delegates to service
├── [domain].service.ts        # Business logic — orchestrates repository + mapper
├── [domain].repository.ts     # Data access — DB queries only (optional if simple)
├── [domain].mapper.ts         # DTO <-> Entity transformation (optional)
├── dto/                       # Request/Response DTOs (Zod or class-validator)
└── entities/                  # Business entities / domain types
```

**When to skip layers:**
- Skip `repository` if the service is simple enough to query directly
- Skip `mapper` if DTOs and entities have identical shapes
- Skip `entities/` if your ORM types serve as domain objects

## Layer Responsibilities

| Layer | Does | Does NOT |
|-------|------|----------|
| **Controller** | Route, validate input, Swagger docs, return response | Business logic, DB queries, error handling beyond HTTP |
| **Service** | Business logic, orchestration, call repository/mapper | Direct DB queries (ideally), HTTP concerns |
| **Repository** | DB queries, data access, error translation | Business rules, response formatting |
| **Mapper** | DTO <-> Entity transformation, naming convention conversion | Business logic, DB queries |

### Controller: Thin by Design

Controllers should be almost boring. They receive validated input, delegate to a service, and return the result. If a controller method exceeds 10 lines of logic, something belongs in the service.

```typescript
@Controller('products')
@ApiTags('products')
export class ProductController {
  constructor(private readonly productService: ProductService) {}

  @Post()
  @ApiOperation({ summary: 'Create product' })
  async create(@Body() dto: CreateProductDto): Promise<ProductResponse> {
    return this.productService.create(dto);
  }

  @Get(':id')
  async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<ProductResponse> {
    return this.productService.findById(id);
  }
}
```

### Service: Where Business Lives

Services contain all business rules and orchestration. They're the only layer that should make decisions.

```typescript
@Injectable()
export class ProductService {
  constructor(
    private readonly productRepository: ProductRepository,
    private readonly mapper: ProductMapper,
  ) {}

  async create(dto: CreateProductDto): Promise<ProductResponse> {
    // Business rule: check uniqueness
    const existing = await this.productRepository.findBySlug(dto.slug);
    if (existing) {
      throw new ConflictException('Product with this slug already exists');
    }

    const entity = await this.productRepository.create(dto);
    return { success: true, data: this.mapper.toApi(entity) };
  }
}
```

## DTOs and Validation

Two approaches, both valid — pick one per project and stay consistent:

### Option A: Zod (recommended for type-safe schemas)

```typescript
import { createZodDto } from 'nestjs-zod';
import { z } from 'zod';

const CreateProductSchema = z.object({
  name: z.string().min(3).max(100),
  price: z.number().positive(),
  description: z.string().max(2000).optional(),
});

export class CreateProductDto extends createZodDto(CreateProductSchema) {}
```

With `ZodValidationPipe` as `APP_PIPE`, validation is automatic.

### Option B: class-validator

```typescript
import { IsString, MinLength, MaxLength, IsNumber, IsOptional, Min } from 'class-validator';

export class CreateProductDto {
  @IsString()
  @MinLength(3)
  @MaxLength(100)
  readonly name: string;

  @IsNumber()
  @Min(0)
  readonly price: number;

  @IsOptional()
  @MaxLength(2000)
  readonly description?: string;
}
```

With `ValidationPipe({ transform: true, whitelist: true, forbidNonWhitelisted: true })` as `APP_PIPE`.

**Key principle:** DTOs are your API contract. They define what goes in and what comes out. Never expose raw database types in API responses — always map through a response DTO.

## Response Patterns

Consistent responses make APIs predictable for clients. See `references/response-patterns.md` for full implementation details.

Two common approaches:

### Envelope response (explicit wrapper)

```typescript
// Success with data
{ "success": true, "data": { ... } }

// Success with message only
{ "success": true, "message": "Product deleted" }

// Error
{ "success": false, "statusCode": 404, "message": "Product not found", "code": "ERR_PRODUCT_NOT_FOUND" }
```

### Direct response (NestJS default)

Controller returns the DTO directly, HTTP status codes carry the semantics. Use interceptors to wrap if you need envelopes.

## Exception Handling

Centralize error handling in a single `ExceptionFilter`. Services throw typed exceptions, the filter catches and formats them consistently. See `references/exception-handling.md` for detailed patterns.

**Core rules:**
- Services **throw** — they never format HTTP responses
- The exception filter **catches and formats** — it's the single point of error response shaping
- **Log OR throw, never both** — the filter handles logging
- Use typed error definitions, not bare string messages

```typescript
// Define errors as constants
export const ERROR_DEFINITIONS = {
  PRODUCT_NOT_FOUND: {
    code: 'ERR_PRODUCT_NOT_FOUND',
    message: (details?: { id?: string }) =>
      details?.id ? `Product '${details.id}' not found` : 'Product not found',
    httpStatus: HttpStatus.NOT_FOUND,
  },
} as const;

// Service throws with context
throw new BusinessException(
  ERROR_DEFINITIONS.PRODUCT_NOT_FOUND,
  { id: productId },                          // Client-visible details
  { operation: 'findById', userId: user.id },  // Logging context (not sent to client)
  { cause: originalError },                    // Error cause chain
);
```

## Guards: Authentication and Authorization

Guards run before the controller and decide whether the request proceeds. See `references/guards-auth.md` for full patterns.

**Layered security model:**

```
Request → ApiKeyGuard → AuthGuard → RolesGuard → Controller
```

1. **API Key Guard** — validates `x-api-key` header, checks permissions
2. **Auth Guard** — validates JWT Bearer token, attaches user to request
3. **Roles Guard** — checks user roles against route requirements

```typescript
// Mark routes as public (skip AuthGuard)
@Public()
@Get('health')
healthCheck() { return 'ok'; }

// Require specific roles
@Roles([RoleCode.ADMIN])
@Controller('admin/products')
export class ProductAdminController { ... }
```

**Register guards globally in the module:**

```typescript
@Module({
  providers: [
    { provide: APP_GUARD, useClass: ApiKeyGuard },
    { provide: APP_GUARD, useClass: AuthGuard },
    { provide: APP_GUARD, useClass: RolesGuard },
  ],
})
export class CoreModule {}
```

## Interceptors

Interceptors wrap the request/response cycle. They run before and after the controller handler.

**Common interceptors:**

| Interceptor | Purpose |
|-------------|---------|
| ResponseTransformer | Wraps raw returns in envelope response |
| ResponseValidation | Validates outgoing DTOs (catches contract violations) |
| CacheInterceptor | Caches GET responses (apply per-route, not globally) |
| LoggingInterceptor | Logs request duration and metadata |

```typescript
// Response transformer — wraps DTOs in standard envelope
@Injectable()
export class ResponseTransformer implements NestInterceptor {
  intercept(_: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      map((data) => {
        if (data?.success !== undefined) return data; // Already wrapped
        if (typeof data === 'string') return { success: true, message: data };
        return { success: true, data };
      }),
    );
  }
}
```

## Module Wiring

The module is where DI comes together. Keep it declarative and predictable.

```typescript
@Module({
  imports: [
    TypeOrmModule.forFeature([ProductEntity]),  // or MongooseModule, etc.
  ],
  controllers: [ProductController],
  providers: [
    ProductService,
    ProductRepository,
    ProductMapper,
  ],
  exports: [ProductService],  // Only export what other modules need
})
export class ProductModule {}
```

**AppModule wires cross-cutting concerns:**

```typescript
@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    CoreModule,       // Guards, pipes, interceptors, filters
    ProductModule,
    OrderModule,
    // ...feature modules
  ],
})
export class AppModule {}
```

## CoreModule Pattern

Centralize all cross-cutting providers in a single module:

```typescript
@Module({
  providers: [
    { provide: APP_INTERCEPTOR, useClass: ResponseTransformer },
    { provide: APP_FILTER, useClass: GlobalExceptionFilter },
    { provide: APP_PIPE, useValue: new ValidationPipe({ transform: true, whitelist: true }) },
    { provide: APP_GUARD, useClass: AuthGuard },
  ],
})
export class CoreModule {}
```

**Execution order within the same provider type follows registration order in the providers array.**

## Config Pattern

Type-safe configuration with validation:

```typescript
// config/database.config.ts
import { registerAs } from '@nestjs/config';

export const DatabaseConfigName = 'database';

export interface DatabaseConfig {
  host: string;
  port: number;
  name: string;
}

export default registerAs(DatabaseConfigName, () => ({
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT || '5432'),
  name: process.env.DB_NAME || '',
}));
```

Use `configService.getOrThrow<DatabaseConfig>(DatabaseConfigName)` — fail fast on missing config.

## Caching

Apply caching surgically on specific read endpoints, not globally:

```typescript
@UseInterceptors(CacheInterceptor)
@Get()
async findAll(): Promise<ProductListResponse> {
  return this.productService.findAll();
}
```

**Invalidate after mutations** — stale cache is worse than no cache.

## Middleware

Middleware runs before guards, for cross-cutting HTTP concerns:

| Middleware | Purpose |
|------------|---------|
| PayloadSize | Reject oversized request bodies |
| RateLimiting | Throttle requests per IP/user |
| RequestId | Attach correlation ID to every request |
| Maintenance | Return 503 when in maintenance mode |

## Consultation Workflow

When the user asks an API design question:

### 1. CLASSIFY the question

- **New feature**: Design the full module structure
- **Endpoint design**: Controller + DTO + service method
- **Error handling**: Exception patterns + error definitions
- **Auth/security**: Guard selection + decorator placement
- **Response format**: Interceptor + DTO design
- **Architecture**: Layer placement decision

### 2. INVESTIGATE the codebase

Before recommending patterns, check what already exists:

```
Glob: src/modules/**/  → existing feature structure
Grep: APP_GUARD|APP_PIPE|APP_INTERCEPTOR|APP_FILTER  → registered providers
Grep: extends.*Exception|throw new  → error handling patterns
Read: app.module.ts → module registration
```

Match existing conventions. Don't introduce new patterns unless the existing ones are inadequate.

### 3. DESIGN the solution

- Start with the feature module structure
- Define DTOs (input validation + response shape)
- Design the controller (routes + decorators)
- Design the service (business logic)
- Add error definitions if needed
- Consider caching, guards, and interceptors

### 4. PRESENT with rationale

Explain **why** each pattern is used, not just what. A developer who understands the reasoning can adapt the pattern to their specific context.

## Reference Files

For detailed implementation patterns, consult these references:

| File | When to read |
|------|-------------|
| `references/response-patterns.md` | Designing response envelopes, status codes, transformers |
| `references/exception-handling.md` | Exception filters, error definitions, cause chains |
| `references/guards-auth.md` | Authentication, authorization, API key patterns |
| `references/custom-decorators-pipes.md` | Custom parameter decorators, validation pipes, transformers |
| `references/caching-config.md` | Redis caching, config registration, database setup |
| `references/testing-patterns.md` | Unit test structure, integration tests, mocking |