diegosouzapw API Implementation Patterns
Template for project-specific API implementation skill Fill in [CUSTOMIZE] sections with your project's detected or chosen patterns
Project: [PROJECT NAME] Framework: [CUSTOMIZE: Spring Boot / Express.js / FastAPI / Django / Ruby on Rails / Gin] Language: [CUSTOMIZE: Java / TypeScript / Python / Ruby / Go] Last Updated: [DATE]
Controller/Route Layer
File Organization
Location: [CUSTOMIZE: src/main/java/controllers / src/controllers / app/routers]
Naming Convention: [CUSTOMIZE: UserController / UsersController / user_controller / user.routes]
Pattern Type: [CUSTOMIZE: Class-based / Function-based / Decorator-based]
Endpoint Definition Pattern
[CUSTOMIZE WITH YOUR PROJECT'S ACTUAL PATTERN]
Example - GET Endpoint:
[CUSTOMIZE: Show actual code pattern from your project]
Example patterns:
- Spring Boot: @GetMapping("/users")
- Express: router.get('/users', async (req, res) => {...})
- FastAPI: @router.get("/users")
- Django: viewsets.ModelViewSet
- Rails: resources :users
Example - POST Endpoint with Validation:
[CUSTOMIZE: Show create/post pattern]
Example - PUT/PATCH Endpoint:
[CUSTOMIZE: Show update pattern]
Example - DELETE Endpoint:
[CUSTOMIZE: Show delete pattern]
Request/Response Handling
Request Body Parsing: [CUSTOMIZE: @RequestBody / req.body / Request / request.data]
Response Format: [CUSTOMIZE: ResponseEntity / res.json() / JSONResponse / render]
Status Codes: [CUSTOMIZE: Which codes used - 200, 201, 204, 400, 404, 500]
Service Layer
File Organization
Location: [CUSTOMIZE: src/main/java/services / src/services / app/services]
Naming: [CUSTOMIZE: UserService / UsersService / user_service / UserService.ts]
Pattern: [CUSTOMIZE: Class-based / Function-based / Module-based]
Business Logic Pattern
[CUSTOMIZE WITH ACTUAL PATTERN]
Example - CRUD Operations:
[CUSTOMIZE: Show service class/module structure]
Example:
- Create: createUser(data) → validates, saves, returns
- Read: getUserById(id) → finds, throws if not found
- Update: updateUser(id, data) → finds, validates, updates
- Delete: deleteUser(id) → checks dependencies, deletes
Transaction Management
Approach: [CUSTOMIZE: @Transactional / BEGIN/COMMIT / context manager / transaction.atomic]
Isolation Level: [CUSTOMIZE: READ_COMMITTED / Default / Custom]
Data Access Layer
File Organization
Location: [CUSTOMIZE: src/main/java/repositories / src/repositories / app/models]
Naming: [CUSTOMIZE: UserRepository / UsersRepository / user_repository]
Pattern: [CUSTOMIZE: Spring Data JPA / Prisma / SQLAlchemy / ActiveRecord / Raw SQL]
Query Pattern
[CUSTOMIZE WITH ACTUAL PATTERN]
Standard Queries:
[CUSTOMIZE: Show query methods]
Examples:
- findById(id)
- findAll()
- save(entity)
- delete(id)
Custom Queries:
[CUSTOMIZE: How custom queries are defined]
Examples:
- Spring Data: findByEmail(email)
- Prisma: findMany({ where: {...}})
- SQLAlchemy: query.filter_by(email=email)
N+1 Query Prevention
Strategy: [CUSTOMIZE: @EntityGraph / .include() / select_related() / eager loading]
Data Models / Entities
File Organization
Location: [CUSTOMIZE: src/main/java/entities / src/models / app/models]
Naming: [CUSTOMIZE: User / UserEntity / user.model / User.java]
Field Naming
Convention: [CUSTOMIZE: camelCase / snake_case / PascalCase]
Examples:
- User ID: [userId / user_id / id]
- Email: [email / emailAddress / email_address]
- Created timestamp: [createdAt / created_at / dateCreated]
Relationships
Pattern: [CUSTOMIZE: @OneToMany / hasMany / ForeignKey / references]
Example:
[CUSTOMIZE: How relationships are defined]
Validation
Location: [CUSTOMIZE: Entity level / DTO level / Separate validators]
Approach: [CUSTOMIZE: Annotations / Decorators / Validator classes / Schemas]
DTOs / Serializers
File Organization
Location: [CUSTOMIZE: src/main/java/dto / src/dto / app/serializers]
Naming Convention: [CUSTOMIZE: UserDTO / UserResponse / CreateUserDTO / user_schema]
Request DTOs
Pattern: [CUSTOMIZE: Records / Classes / Interfaces / Pydantic models]
Example:
[CUSTOMIZE: Show CreateRequest pattern]
Validation: [CUSTOMIZE: @Valid / class-validator / Pydantic / Rails validations]
Response DTOs
Pattern: [CUSTOMIZE: Same as request / Separate / ViewModels]
Example:
[CUSTOMIZE: Show Response DTO]
Mapping
Approach: [CUSTOMIZE: Manual / MapStruct / class-transformer / Serializer]
Exception Handling
Custom Exceptions
Location: [CUSTOMIZE: src/exceptions / src/errors / app/exceptions]
Naming: [CUSTOMIZE: ResourceNotFoundException / NotFoundError / ResourceNotFound]
Example:
[CUSTOMIZE: Show custom exception]
Global Handler
Pattern: [CUSTOMIZE: @ControllerAdvice / middleware / exception_handler / rescue_from]
Error Response Format:
[CUSTOMIZE: Show your error response structure]
{
"status": 404,
"message": "User not found",
"timestamp": "2025-12-30T10:00:00Z"
}
Testing Patterns
Unit Tests
Framework: [CUSTOMIZE: JUnit 5 / Jest / Pytest / RSpec]
Mocking: [CUSTOMIZE: Mockito / sinon / unittest.mock / RSpec mocks]
Test Structure: [CUSTOMIZE: AAA / Given-When-Then / Arrange-Act-Assert]
Example:
[CUSTOMIZE: Show unit test pattern]
Integration Tests
Framework: [CUSTOMIZE: Spring Test / Supertest / TestContainers / Django TestCase]
Database: [CUSTOMIZE: TestContainers / In-memory / Rollback / Fixtures]
Example:
[CUSTOMIZE: Show integration test]
API Documentation
Format
Approach: [CUSTOMIZE: OpenAPI/Swagger / JSDoc / Docstrings / YARD / Inline comments]
Mock Generation
Location: [CUSTOMIZE: api-mocks/ / mocks/ / fixtures/]
Format:
[CUSTOMIZE: Show mock structure]
Security Patterns
Input Validation
Where: [CUSTOMIZE: Controller / DTO / Middleware / Before filter]
How: [CUSTOMIZE: Annotations / Decorators / Manual checks / Validators]
SQL Injection Prevention
Approach: [CUSTOMIZE: Parameterized queries / ORM only / Prepared statements]
Authentication
Pattern: [CUSTOMIZE: JWT / Session / OAuth / API Keys]
Code Generation Checklist
When generating API code, always include:
- Controller with all endpoints (GET, POST, PUT, DELETE)
- Service layer with business logic
- Repository/Data access layer
- Entity/Model with proper fields
- Request DTOs with validation
- Response DTOs
- Custom exceptions for domain errors
- Global exception handler
- Unit tests (>80% coverage)
- Integration tests (API endpoints)
- API mocks for frontend
- [PROJECT-SPECIFIC ITEM]
Project-Specific Conventions
[CUSTOMIZE - ADD PROJECT GOTCHAS AND PREFERENCES]
Naming Conventions
- [e.g., Controllers always plural: UsersController not UserController]
- [e.g., Services always singular: UserService]
Code Review Requirements
- [e.g., All public methods must have JavaDoc]
- [e.g., Complex logic needs inline comments]
Performance Considerations
- [e.g., Always paginate list endpoints]
- [e.g., Use database indexes on foreign keys]
Customization Complete: Replace all [CUSTOMIZE] sections with project-detected or chosen patterns.
Auto-generated by: /add-skill api-implementation-patterns command (with code analysis)