@vodailoc/kilo-kit-mcp 1.1.0 → 1.1.1

package/skills/kilo-kit/development/backend/SKILL.md

@@ -1,540 +1,540 @@
----
-name: backend-api-development
-description: >-
-  Comprehensive backend API development skill for building robust, scalable APIs.
-  Use when creating new endpoints, services, or backend functionality.
-  Keywords: API, backend, endpoint, service, REST, GraphQL, server, controller, route
-version: 1.0.0
-behaviors: [generate_with_validation, investigate_codebase, document_code, test_change]
-dependencies: []
-token_estimate:
-  min: 2000
-  typical: 5000
-  max: 12000
----
-
-# 🔧 Backend API Development Skill
-
-> **Philosophy:** APIs are contracts. Build them right the first time.
-
-## When to Use
-
-Use this skill when:
-- Creating a new API endpoint
-- Building a new service/module
-- Refactoring existing API code
-- Adding new functionality to backend
-- Need to follow RESTful/GraphQL best practices
-
-**Do NOT use this skill when:**
-- Just fixing a small bug (use debugging skill)
-- Only modifying frontend (use frontend skill)
-- Database-only changes (use database skill)
-
----
-
-## Prerequisites
-
-Before starting:
-- [ ] Requirements are clear (what the API should do)
-- [ ] Understand the existing architecture
-- [ ] Know the target stack (NestJS, Express, FastAPI, etc.)
-- [ ] Database schema exists (or will be created)
-
----
-
-## Process
-
-### Phase 1: DESIGN 📐
-
-**Goal:** Design the API before writing code.
-
-**Steps:**
-
-1. **Define the Resource**
-   ```yaml
-   resource:
-     name: User
-     description: Represents a platform user
-     domain: authentication
-   ```
-
-2. **Design Endpoints (REST)**
-   ```yaml
-   endpoints:
-     - method: GET
-       path: /users
-       description: List all users
-       query_params: [page, limit, search]
-       response: User[]
-     
-     - method: GET
-       path: /users/:id
-       description: Get single user
-       response: User
-     
-     - method: POST
-       path: /users
-       description: Create new user
-       body: CreateUserDto
-       response: User
-     
-     - method: PUT
-       path: /users/:id
-       description: Update user
-       body: UpdateUserDto
-       response: User
-     
-     - method: DELETE
-       path: /users/:id
-       description: Delete user
-       response: void
-   ```
-
-3. **Define DTOs (Data Transfer Objects)**
-   ```typescript
-   // CreateUserDto
-   interface CreateUserDto {
-     email: string;      // required, email format
-     password: string;   // required, min 8 chars
-     name: string;       // required, min 2 chars
-     role?: UserRole;    // optional, default: 'user'
-   }
-   
-   // UpdateUserDto
-   type UpdateUserDto = Partial<CreateUserDto>;
-   
-   // UserResponseDto
-   interface UserResponseDto {
-     id: string;
-     email: string;
-     name: string;
-     role: UserRole;
-     createdAt: DateTime;
-     updatedAt: DateTime;
-     // Note: password NOT included
-   }
-   ```
-
-4. **Plan Error Responses**
-   ```yaml
-   errors:
-     - code: 400
-       when: Invalid input
-       response: { message, errors: [{field, message}] }
-     
-     - code: 401
-       when: Not authenticated
-       response: { message: "Unauthorized" }
-     
-     - code: 403
-       when: Not authorized
-       response: { message: "Forbidden" }
-     
-     - code: 404
-       when: Resource not found
-       response: { message: "User not found" }
-     
-     - code: 409
-       when: Conflict (e.g., email exists)
-       response: { message: "Email already registered" }
-   ```
-
-**Output:** Complete API design document.
-
----
-
-### Phase 2: STRUCTURE 🏗️
-
-**Goal:** Set up the file structure.
-
-**NestJS Structure:**
-```
-src/
-└── users/
-    ├── users.module.ts       # Module definition
-    ├── users.controller.ts   # HTTP layer
-    ├── users.service.ts      # Business logic
-    ├── users.repository.ts   # Data access (optional)
-    ├── dto/
-    │   ├── create-user.dto.ts
-    │   ├── update-user.dto.ts
-    │   └── user-response.dto.ts
-    ├── entities/
-    │   └── user.entity.ts
-    ├── guards/
-    │   └── user-owner.guard.ts
-    └── users.controller.spec.ts
-```
-
-**FastAPI Structure:**
-```
-app/
-└── users/
-    ├── __init__.py
-    ├── router.py          # Routes
-    ├── service.py         # Business logic
-    ├── repository.py      # Data access
-    ├── schemas.py         # Pydantic models
-    ├── models.py          # SQLAlchemy models
-    └── dependencies.py    # Dependency injection
-```
-
----
-
-### Phase 3: IMPLEMENTATION 💻
-
-**Goal:** Implement the API layer by layer.
-
-**Order of Implementation:**
-
-1. **Entity/Model First**
-   ```typescript
-   // user.entity.ts
-   @Entity('users')
-   export class User {
-     @PrimaryGeneratedColumn('uuid')
-     id: string;
-     
-     @Column({ unique: true })
-     @IsEmail()
-     email: string;
-     
-     @Column()
-     @Exclude() // Never expose password
-     password: string;
-     
-     @Column()
-     name: string;
-     
-     @Column({ default: 'user' })
-     role: UserRole;
-     
-     @CreateDateColumn()
-     createdAt: Date;
-     
-     @UpdateDateColumn()
-     updatedAt: Date;
-   }
-   ```
-
-2. **DTOs with Validation**
-   ```typescript
-   // create-user.dto.ts
-   export class CreateUserDto {
-     @IsEmail()
-     @Transform(({ value }) => value.toLowerCase().trim())
-     email: string;
-     
-     @IsString()
-     @MinLength(8)
-     @Matches(/^(?=.*[A-Za-z])(?=.*\d)/, {
-       message: 'Password must contain letters and numbers'
-     })
-     password: string;
-     
-     @IsString()
-     @MinLength(2)
-     @MaxLength(50)
-     name: string;
-     
-     @IsOptional()
-     @IsEnum(UserRole)
-     role?: UserRole;
-   }
-   ```
-
-3. **Service Layer (Business Logic)**
-   ```typescript
-   // users.service.ts
-   @Injectable()
-   export class UsersService {
-     constructor(
-       @InjectRepository(User)
-       private usersRepository: Repository<User>,
-     ) {}
-     
-     async create(dto: CreateUserDto): Promise<User> {
-       // Check for existing email
-       const existing = await this.findByEmail(dto.email);
-       if (existing) {
-         throw new ConflictException('Email already registered');
-       }
-       
-       // Hash password
-       const hashedPassword = await bcrypt.hash(dto.password, 10);
-       
-       // Create and save
-       const user = this.usersRepository.create({
-         ...dto,
-         password: hashedPassword,
-       });
-       
-       return this.usersRepository.save(user);
-     }
-     
-     async findAll(options: PaginationOptions): Promise<PaginatedResult<User>> {
-       // Implementation with pagination
-     }
-     
-     // ... other methods
-   }
-   ```
-
-4. **Controller (HTTP Layer)**
-   ```typescript
-   // users.controller.ts
-   @Controller('users')
-   @UseInterceptors(ClassSerializerInterceptor)
-   export class UsersController {
-     constructor(private readonly usersService: UsersService) {}
-     
-     @Post()
-     @HttpCode(HttpStatus.CREATED)
-     async create(@Body() dto: CreateUserDto): Promise<UserResponseDto> {
-       const user = await this.usersService.create(dto);
-       return plainToInstance(UserResponseDto, user);
-     }
-     
-     @Get()
-     @UseGuards(AuthGuard)
-     async findAll(
-       @Query() query: PaginationQueryDto
-     ): Promise<PaginatedResult<UserResponseDto>> {
-       return this.usersService.findAll(query);
-     }
-     
-     @Get(':id')
-     @UseGuards(AuthGuard)
-     async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<UserResponseDto> {
-       const user = await this.usersService.findOne(id);
-       if (!user) {
-         throw new NotFoundException('User not found');
-       }
-       return plainToInstance(UserResponseDto, user);
-     }
-     
-     // ... other endpoints
-   }
-   ```
-
----
-
-### Phase 4: SECURITY 🔒
-
-**Goal:** Ensure API is secure.
-
-**Security Checklist:**
-
-1. **Input Validation**
-   - [ ] All inputs validated with DTOs
-   - [ ] Types enforced
-   - [ ] Length limits set
-   - [ ] Format validation (email, UUID, etc.)
-
-2. **Authentication**
-   - [ ] Protected routes require authentication
-   - [ ] JWT or session validation
-   - [ ] Token expiration handled
-
-3. **Authorization**
-   - [ ] Role-based access control
-   - [ ] Resource ownership verified
-   - [ ] Admin-only routes protected
-
-4. **Data Protection**
-   - [ ] Passwords hashed (bcrypt, argon2)
-   - [ ] Sensitive data not logged
-   - [ ] Passwords excluded from responses
-
-5. **Rate Limiting**
-   - [ ] Login attempts limited
-   - [ ] API rate limiting in place
-
-6. **SQL Injection Prevention**
-   - [ ] Parameterized queries used
-   - [ ] ORM used correctly
-   - [ ] Raw queries avoided or sanitized
-
----
-
-### Phase 5: TESTING 🧪
-
-**Goal:** Write comprehensive tests.
-
-**Test Types:**
-
-1. **Unit Tests**
-   ```typescript
-   describe('UsersService', () => {
-     describe('create', () => {
-       it('should create a new user', async () => {
-         const dto = { email: 'test@example.com', ... };
-         const result = await service.create(dto);
-         expect(result.email).toBe(dto.email);
-       });
-       
-       it('should hash the password', async () => {
-         const dto = { password: 'plaintext', ... };
-         const result = await service.create(dto);
-         expect(result.password).not.toBe(dto.password);
-       });
-       
-       it('should throw on duplicate email', async () => {
-         // Setup: create user first
-         await service.create({ email: 'test@example.com', ... });
-         
-         // Act & Assert
-         await expect(
-           service.create({ email: 'test@example.com', ... })
-         ).rejects.toThrow(ConflictException);
-       });
-     });
-   });
-   ```
-
-2. **Integration Tests**
-   ```typescript
-   describe('Users API', () => {
-     it('POST /users should create user', async () => {
-       const response = await request(app.getHttpServer())
-         .post('/users')
-         .send({ email: 'test@example.com', password: 'Password1', name: 'Test' })
-         .expect(201);
-       
-       expect(response.body.email).toBe('test@example.com');
-       expect(response.body.password).toBeUndefined();
-     });
-     
-     it('GET /users should require auth', async () => {
-       await request(app.getHttpServer())
-         .get('/users')
-         .expect(401);
-     });
-   });
-   ```
-
----
-
-### Phase 6: DOCUMENTATION 📝
-
-**Goal:** Document the API.
-
-**OpenAPI/Swagger:**
-```typescript
-@ApiTags('users')
-@Controller('users')
-export class UsersController {
-  @Post()
-  @ApiOperation({ summary: 'Create a new user' })
-  @ApiResponse({ status: 201, type: UserResponseDto })
-  @ApiResponse({ status: 400, description: 'Invalid input' })
-  @ApiResponse({ status: 409, description: 'Email already exists' })
-  async create(@Body() dto: CreateUserDto): Promise<UserResponseDto> {
-    // ...
-  }
-}
-```
-
-**Response DTO Documentation:**
-```typescript
-export class UserResponseDto {
-  @ApiProperty({ example: '550e8400-e29b-41d4-a716-446655440000' })
-  id: string;
-  
-  @ApiProperty({ example: 'user@example.com' })
-  email: string;
-  
-  @ApiProperty({ example: 'John Doe' })
-  name: string;
-}
-```
-
----
-
-## Best Practices
-
-### API Design
-
-| Practice | Do | Don't |
-|----------|----|----- |
-| Naming | `GET /users/:id/orders` | `GET /getUserOrders` |
-| Versioning | `/api/v1/users` | No versioning |
-| Pluralization | `/users`, `/orders` | `/user`, `/order` |
-| HTTP Methods | Use correctly (GET=read, POST=create) | POST for everything |
-| Status Codes | 201 for created, 204 for no content | 200 for everything |
-
-### Error Handling
-
-```typescript
-// Global exception filter
-@Catch()
-export class AllExceptionsFilter implements ExceptionFilter {
-  catch(exception: unknown, host: ArgumentsHost) {
-    const ctx = host.switchToHttp();
-    const response = ctx.getResponse<Response>();
-    
-    const status = exception instanceof HttpException
-      ? exception.getStatus()
-      : HttpStatus.INTERNAL_SERVER_ERROR;
-    
-    const message = exception instanceof HttpException
-      ? exception.message
-      : 'Internal server error';
-    
-    response.status(status).json({
-      statusCode: status,
-      message,
-      timestamp: new Date().toISOString(),
-    });
-  }
-}
-```
-
----
-
-## Guidelines
-
-### DO ✅
-- Design API before coding
-- Use proper HTTP methods and status codes
-- Validate all inputs
-- Handle errors gracefully
-- Write tests first (TDD)
-- Document with OpenAPI
-
-### DON'T ❌
-- Expose internal IDs when UUIDs are better
-- Return password or sensitive data
-- Use GET for mutations
-- Skip input validation
-- Catch and swallow errors
-- Use magic strings/numbers
-
----
-
-## Success Criteria
-
-Before considering API complete:
-
-- [ ] All endpoints implemented per design
-- [ ] Input validation on all endpoints
-- [ ] Authentication/Authorization in place
-- [ ] Error handling comprehensive
-- [ ] Unit tests with >80% coverage
-- [ ] Integration tests for main flows
-- [ ] API documented (OpenAPI/Swagger)
-- [ ] Security checklist passed
-
----
-
-## Related Skills
-
-- `skills/kilo-kit/development/database/` - For data layer
-- `skills/kilo-kit/development/security/` - For security concerns
-- `skills/kilo-kit/quality/testing/` - For test coverage
-- `skills/kilo-kit/architecture/system-design/` - For architecture decisions
-
----
-
-*Backend API Development Skill v1.0.0 — APIs built right*
+---
+name: backend-api-development
+description: >-
+  Comprehensive backend API development skill for building robust, scalable APIs.
+  Use when creating new endpoints, services, or backend functionality.
+  Keywords: API, backend, endpoint, service, REST, GraphQL, server, controller, route
+version: 1.0.0
+behaviors: [generate_with_validation, investigate_codebase, document_code, test_change]
+dependencies: []
+token_estimate:
+  min: 2000
+  typical: 5000
+  max: 12000
+---
+
+# 🔧 Backend API Development Skill
+
+> **Philosophy:** APIs are contracts. Build them right the first time.
+
+## When to Use
+
+Use this skill when:
+- Creating a new API endpoint
+- Building a new service/module
+- Refactoring existing API code
+- Adding new functionality to backend
+- Need to follow RESTful/GraphQL best practices
+
+**Do NOT use this skill when:**
+- Just fixing a small bug (use debugging skill)
+- Only modifying frontend (use frontend skill)
+- Database-only changes (use database skill)
+
+---
+
+## Prerequisites
+
+Before starting:
+- [ ] Requirements are clear (what the API should do)
+- [ ] Understand the existing architecture
+- [ ] Know the target stack (NestJS, Express, FastAPI, etc.)
+- [ ] Database schema exists (or will be created)
+
+---
+
+## Process
+
+### Phase 1: DESIGN 📐
+
+**Goal:** Design the API before writing code.
+
+**Steps:**
+
+1. **Define the Resource**
+   ```yaml
+   resource:
+     name: User
+     description: Represents a platform user
+     domain: authentication
+   ```
+
+2. **Design Endpoints (REST)**
+   ```yaml
+   endpoints:
+     - method: GET
+       path: /users
+       description: List all users
+       query_params: [page, limit, search]
+       response: User[]
+     
+     - method: GET
+       path: /users/:id
+       description: Get single user
+       response: User
+     
+     - method: POST
+       path: /users
+       description: Create new user
+       body: CreateUserDto
+       response: User
+     
+     - method: PUT
+       path: /users/:id
+       description: Update user
+       body: UpdateUserDto
+       response: User
+     
+     - method: DELETE
+       path: /users/:id
+       description: Delete user
+       response: void
+   ```
+
+3. **Define DTOs (Data Transfer Objects)**
+   ```typescript
+   // CreateUserDto
+   interface CreateUserDto {
+     email: string;      // required, email format
+     password: string;   // required, min 8 chars
+     name: string;       // required, min 2 chars
+     role?: UserRole;    // optional, default: 'user'
+   }
+   
+   // UpdateUserDto
+   type UpdateUserDto = Partial<CreateUserDto>;
+   
+   // UserResponseDto
+   interface UserResponseDto {
+     id: string;
+     email: string;
+     name: string;
+     role: UserRole;
+     createdAt: DateTime;
+     updatedAt: DateTime;
+     // Note: password NOT included
+   }
+   ```
+
+4. **Plan Error Responses**
+   ```yaml
+   errors:
+     - code: 400
+       when: Invalid input
+       response: { message, errors: [{field, message}] }
+     
+     - code: 401
+       when: Not authenticated
+       response: { message: "Unauthorized" }
+     
+     - code: 403
+       when: Not authorized
+       response: { message: "Forbidden" }
+     
+     - code: 404
+       when: Resource not found
+       response: { message: "User not found" }
+     
+     - code: 409
+       when: Conflict (e.g., email exists)
+       response: { message: "Email already registered" }
+   ```
+
+**Output:** Complete API design document.
+
+---
+
+### Phase 2: STRUCTURE 🏗️
+
+**Goal:** Set up the file structure.
+
+**NestJS Structure:**
+```
+src/
+└── users/
+    ├── users.module.ts       # Module definition
+    ├── users.controller.ts   # HTTP layer
+    ├── users.service.ts      # Business logic
+    ├── users.repository.ts   # Data access (optional)
+    ├── dto/
+    │   ├── create-user.dto.ts
+    │   ├── update-user.dto.ts
+    │   └── user-response.dto.ts
+    ├── entities/
+    │   └── user.entity.ts
+    ├── guards/
+    │   └── user-owner.guard.ts
+    └── users.controller.spec.ts
+```
+
+**FastAPI Structure:**
+```
+app/
+└── users/
+    ├── __init__.py
+    ├── router.py          # Routes
+    ├── service.py         # Business logic
+    ├── repository.py      # Data access
+    ├── schemas.py         # Pydantic models
+    ├── models.py          # SQLAlchemy models
+    └── dependencies.py    # Dependency injection
+```
+
+---
+
+### Phase 3: IMPLEMENTATION 💻
+
+**Goal:** Implement the API layer by layer.
+
+**Order of Implementation:**
+
+1. **Entity/Model First**
+   ```typescript
+   // user.entity.ts
+   @Entity('users')
+   export class User {
+     @PrimaryGeneratedColumn('uuid')
+     id: string;
+     
+     @Column({ unique: true })
+     @IsEmail()
+     email: string;
+     
+     @Column()
+     @Exclude() // Never expose password
+     password: string;
+     
+     @Column()
+     name: string;
+     
+     @Column({ default: 'user' })
+     role: UserRole;
+     
+     @CreateDateColumn()
+     createdAt: Date;
+     
+     @UpdateDateColumn()
+     updatedAt: Date;
+   }
+   ```
+
+2. **DTOs with Validation**
+   ```typescript
+   // create-user.dto.ts
+   export class CreateUserDto {
+     @IsEmail()
+     @Transform(({ value }) => value.toLowerCase().trim())
+     email: string;
+     
+     @IsString()
+     @MinLength(8)
+     @Matches(/^(?=.*[A-Za-z])(?=.*\d)/, {
+       message: 'Password must contain letters and numbers'
+     })
+     password: string;
+     
+     @IsString()
+     @MinLength(2)
+     @MaxLength(50)
+     name: string;
+     
+     @IsOptional()
+     @IsEnum(UserRole)
+     role?: UserRole;
+   }
+   ```
+
+3. **Service Layer (Business Logic)**
+   ```typescript
+   // users.service.ts
+   @Injectable()
+   export class UsersService {
+     constructor(
+       @InjectRepository(User)
+       private usersRepository: Repository<User>,
+     ) {}
+     
+     async create(dto: CreateUserDto): Promise<User> {
+       // Check for existing email
+       const existing = await this.findByEmail(dto.email);
+       if (existing) {
+         throw new ConflictException('Email already registered');
+       }
+       
+       // Hash password
+       const hashedPassword = await bcrypt.hash(dto.password, 10);
+       
+       // Create and save
+       const user = this.usersRepository.create({
+         ...dto,
+         password: hashedPassword,
+       });
+       
+       return this.usersRepository.save(user);
+     }
+     
+     async findAll(options: PaginationOptions): Promise<PaginatedResult<User>> {
+       // Implementation with pagination
+     }
+     
+     // ... other methods
+   }
+   ```
+
+4. **Controller (HTTP Layer)**
+   ```typescript
+   // users.controller.ts
+   @Controller('users')
+   @UseInterceptors(ClassSerializerInterceptor)
+   export class UsersController {
+     constructor(private readonly usersService: UsersService) {}
+     
+     @Post()
+     @HttpCode(HttpStatus.CREATED)
+     async create(@Body() dto: CreateUserDto): Promise<UserResponseDto> {
+       const user = await this.usersService.create(dto);
+       return plainToInstance(UserResponseDto, user);
+     }
+     
+     @Get()
+     @UseGuards(AuthGuard)
+     async findAll(
+       @Query() query: PaginationQueryDto
+     ): Promise<PaginatedResult<UserResponseDto>> {
+       return this.usersService.findAll(query);
+     }
+     
+     @Get(':id')
+     @UseGuards(AuthGuard)
+     async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<UserResponseDto> {
+       const user = await this.usersService.findOne(id);
+       if (!user) {
+         throw new NotFoundException('User not found');
+       }
+       return plainToInstance(UserResponseDto, user);
+     }
+     
+     // ... other endpoints
+   }
+   ```
+
+---
+
+### Phase 4: SECURITY 🔒
+
+**Goal:** Ensure API is secure.
+
+**Security Checklist:**
+
+1. **Input Validation**
+   - [ ] All inputs validated with DTOs
+   - [ ] Types enforced
+   - [ ] Length limits set
+   - [ ] Format validation (email, UUID, etc.)
+
+2. **Authentication**
+   - [ ] Protected routes require authentication
+   - [ ] JWT or session validation
+   - [ ] Token expiration handled
+
+3. **Authorization**
+   - [ ] Role-based access control
+   - [ ] Resource ownership verified
+   - [ ] Admin-only routes protected
+
+4. **Data Protection**
+   - [ ] Passwords hashed (bcrypt, argon2)
+   - [ ] Sensitive data not logged
+   - [ ] Passwords excluded from responses
+
+5. **Rate Limiting**
+   - [ ] Login attempts limited
+   - [ ] API rate limiting in place
+
+6. **SQL Injection Prevention**
+   - [ ] Parameterized queries used
+   - [ ] ORM used correctly
+   - [ ] Raw queries avoided or sanitized
+
+---
+
+### Phase 5: TESTING 🧪
+
+**Goal:** Write comprehensive tests.
+
+**Test Types:**
+
+1. **Unit Tests**
+   ```typescript
+   describe('UsersService', () => {
+     describe('create', () => {
+       it('should create a new user', async () => {
+         const dto = { email: 'test@example.com', ... };
+         const result = await service.create(dto);
+         expect(result.email).toBe(dto.email);
+       });
+       
+       it('should hash the password', async () => {
+         const dto = { password: 'plaintext', ... };
+         const result = await service.create(dto);
+         expect(result.password).not.toBe(dto.password);
+       });
+       
+       it('should throw on duplicate email', async () => {
+         // Setup: create user first
+         await service.create({ email: 'test@example.com', ... });
+         
+         // Act & Assert
+         await expect(
+           service.create({ email: 'test@example.com', ... })
+         ).rejects.toThrow(ConflictException);
+       });
+     });
+   });
+   ```
+
+2. **Integration Tests**
+   ```typescript
+   describe('Users API', () => {
+     it('POST /users should create user', async () => {
+       const response = await request(app.getHttpServer())
+         .post('/users')
+         .send({ email: 'test@example.com', password: 'Password1', name: 'Test' })
+         .expect(201);
+       
+       expect(response.body.email).toBe('test@example.com');
+       expect(response.body.password).toBeUndefined();
+     });
+     
+     it('GET /users should require auth', async () => {
+       await request(app.getHttpServer())
+         .get('/users')
+         .expect(401);
+     });
+   });
+   ```
+
+---
+
+### Phase 6: DOCUMENTATION 📝
+
+**Goal:** Document the API.
+
+**OpenAPI/Swagger:**
+```typescript
+@ApiTags('users')
+@Controller('users')
+export class UsersController {
+  @Post()
+  @ApiOperation({ summary: 'Create a new user' })
+  @ApiResponse({ status: 201, type: UserResponseDto })
+  @ApiResponse({ status: 400, description: 'Invalid input' })
+  @ApiResponse({ status: 409, description: 'Email already exists' })
+  async create(@Body() dto: CreateUserDto): Promise<UserResponseDto> {
+    // ...
+  }
+}
+```
+
+**Response DTO Documentation:**
+```typescript
+export class UserResponseDto {
+  @ApiProperty({ example: '550e8400-e29b-41d4-a716-446655440000' })
+  id: string;
+  
+  @ApiProperty({ example: 'user@example.com' })
+  email: string;
+  
+  @ApiProperty({ example: 'John Doe' })
+  name: string;
+}
+```
+
+---
+
+## Best Practices
+
+### API Design
+
+| Practice | Do | Don't |
+|----------|----|----- |
+| Naming | `GET /users/:id/orders` | `GET /getUserOrders` |
+| Versioning | `/api/v1/users` | No versioning |
+| Pluralization | `/users`, `/orders` | `/user`, `/order` |
+| HTTP Methods | Use correctly (GET=read, POST=create) | POST for everything |
+| Status Codes | 201 for created, 204 for no content | 200 for everything |
+
+### Error Handling
+
+```typescript
+// Global exception filter
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    
+    const status = exception instanceof HttpException
+      ? exception.getStatus()
+      : HttpStatus.INTERNAL_SERVER_ERROR;
+    
+    const message = exception instanceof HttpException
+      ? exception.message
+      : 'Internal server error';
+    
+    response.status(status).json({
+      statusCode: status,
+      message,
+      timestamp: new Date().toISOString(),
+    });
+  }
+}
+```
+
+---
+
+## Guidelines
+
+### DO ✅
+- Design API before coding
+- Use proper HTTP methods and status codes
+- Validate all inputs
+- Handle errors gracefully
+- Write tests first (TDD)
+- Document with OpenAPI
+
+### DON'T ❌
+- Expose internal IDs when UUIDs are better
+- Return password or sensitive data
+- Use GET for mutations
+- Skip input validation
+- Catch and swallow errors
+- Use magic strings/numbers
+
+---
+
+## Success Criteria
+
+Before considering API complete:
+
+- [ ] All endpoints implemented per design
+- [ ] Input validation on all endpoints
+- [ ] Authentication/Authorization in place
+- [ ] Error handling comprehensive
+- [ ] Unit tests with >80% coverage
+- [ ] Integration tests for main flows
+- [ ] API documented (OpenAPI/Swagger)
+- [ ] Security checklist passed
+
+---
+
+## Related Skills
+
+- `skills/kilo-kit/development/database/` - For data layer
+- `skills/kilo-kit/development/security/` - For security concerns
+- `skills/kilo-kit/quality/testing/` - For test coverage
+- `skills/kilo-kit/architecture/system-design/` - For architecture decisions
+
+---
+
+*Backend API Development Skill v1.0.0 — APIs built right*