api-design

name	api-design
description	Design RESTful APIs following best practices. Use when Designing new API endpoints, Restructuring existing APIs, or Planning API versioning strategy

Project Context

This project uses NestJS with class-validator DTOs. Controllers live in src/modules/<feature>/controller/. Use PageOptionsDto from src/modules/pagination/dto/page_options.dto.ts for paginated list endpoints. Auth is JWT — protected routes use @UseGuards. Swagger decorators (@ApiOperation, @ApiResponse) go on all controller methods.

Workflow

1. Define the resources and their relationships
2. Choose appropriate HTTP methods
3. Design URL structure following REST conventions
4. Define request/response DTOs with class-validator decorators
5. Plan error handling — use Either<DomainError, Response> in use cases, map Left to HTTP errors in controller
6. Add pagination with PageOptionsDto for list endpoints
7. Add Swagger decorators to document the endpoint

Examples

NestJS endpoint design:

// Controller
@Post('users')
@ApiOperation({ summary: 'Create a user' })
@ApiResponse({ status: 201, type: CreateUserResponseDto })
async create(@Body() dto: CreateUserDto): Promise<CreateUserResponseDto> {
  const result = await this.createUserUseCase.execute({ email: dto.email, password: dto.password });
  if (result.isLeft()) throw new BadRequestException(result.value.message);
  return result.value;
}

// DTO
export class CreateUserDto {
  @IsEmail()
  email: string;

  @MinLength(8)
  password: string;
}

Paginated list:

GET /api/v1/users?page=1&take=20
// Uses PageOptionsDto: { page, take, order }

Error responses follow NestJS HttpException format:

{ "statusCode": 400, "message": "Email already in use", "error": "Bad Request" }

Quality Bar

• Use nouns for resources, not verbs
• Use proper HTTP methods and status codes (201 for create, 204 for delete)
• Controllers must never contain business logic — delegate to use cases
• Map Left results to appropriate HTTP exceptions; never expose internal error details
• All endpoints must have Swagger decorators
• Paginated endpoints must use PageOptionsDto and enforce a max page size
• Protected endpoints must have @UseGuards