Backend API Generation Skill

<!-- Generated by tools/exporter.py from skills/backend_skill.md -->
<!-- Do not edit manually. Re-run: python tools/exporter.py -->

# Backend API Generation Skill

## Purpose

This skill provides a comprehensive framework for generating production-grade backend APIs across Python (FastAPI) and Java (Spring Boot) ecosystems. It combines the advanced coding standards from `python_advanced_skill` and `java_advanced_skill` with API-specific patterns for route design, input validation, authentication, error handling, and testing.

The skill ensures consistent API contracts, security best practices, and maintainability across different backend platforms.

## Input

### Task Specification
- **API endpoint requirements**: List of endpoints with HTTP methods (GET, POST, PUT, DELETE, PATCH)
- **Authentication type**: JWT, OAuth2, API key, or none
- **Data models**: Entity definitions with relationships and validation rules
- **Business logic**: Core algorithms and business rules to implement
- **Error scenarios**: Expected failure cases and error codes
- **Performance requirements**: Throughput, latency, and concurrency targets

### Context
- **Platform choice**: Python (FastAPI) or Java (Spring Boot)
- **Database**: PostgreSQL, MySQL, MongoDB, or in-memory
- **Existing services**: References to other microservices or external APIs
- **Compliance requirements**: GDPR, PCI-DSS, SOC2, or industry-specific
- **Team expertise**: Current team skill levels and tech preferences

### Tech Stack
- **Python Stack**: FastAPI 0.104+, Pydantic 2.x, SQLAlchemy 2.x, python-jose for JWT
- **Java Stack**: Spring Boot 3.x, Spring Security, Spring Data JPA, jsonwebtoken
- **Shared**: RESTful design patterns, OpenAPI/Swagger documentation, comprehensive testing

## Output

### API Routes
- Fully implemented endpoint handlers with proper HTTP methods and status codes
- Route grouping using routers/controllers for maintainability
- Input/output serialization with Pydantic models (Python) or DTOs (Java)
- Query parameter validation and path parameter extraction

### Data Models
- Domain entities with all relationships defined
- Validation constraints (required fields, length limits, regex patterns)
- Serialization models for API responses
- Change audit fields (created_at, updated_at, created_by, updated_by)

### Service Layer
- Business logic isolated in service classes
- Transaction management and ACID compliance
- Caching strategies for frequently accessed data
- Error handling with custom exceptions

### Database Schemas
- SQL DDL statements for table creation
- Indexes for performance optimization
- Foreign key constraints and relationships
- Migration scripts for schema evolution

### Comprehensive Tests
- Unit tests for business logic with 80%+ code coverage
- Integration tests for API endpoints
- Authentication/authorization tests
- Error scenario validation
- Performance/load tests for critical paths

## Process

### Step 1: Analyze Requirements
- Understand the problem domain and business rules
- Identify all API endpoints and their operations
- Map data models and relationships
- Determine authentication and authorization needs
- List error scenarios and their handling strategies

### Step 2: Design API Contract
- Define endpoint paths following REST conventions (`/api/v1/resource`)
- Specify HTTP methods (GET for reads, POST for creates, PUT/PATCH for updates, DELETE for deletions)
- Design request/response body schemas
- Plan error response format
- Document with OpenAPI/Swagger specs

### Step 3: Implement Data Models
- Create Pydantic models (Python) or JPA entities (Java) with validation
- Include audit fields (created_at, updated_at, created_by)
- Define relationships (one-to-many, many-to-many)
- Add constraints and indexes for performance

### Step 4: Implement Authentication/Authorization
- Set up JWT token generation and validation
- Implement password hashing (bcrypt)
- Create middleware/filters for route protection
- Design role-based access control (RBAC) if needed

### Step 5: Implement Routes with Input Validation
- Create route handlers/controller methods
- Add Pydantic field validation (Python) or Bean Validation (Java)
- Implement proper error handling with meaningful messages
- Return correct HTTP status codes (200, 201, 204, 400, 401, 403, 404, 409, 500)

### Step 6: Implement Service Layer
- Extract business logic into service classes
- Ensure separation of concerns between routes and business logic
- Handle transactions properly
- Implement proper exception handling

### Step 7: Write Comprehensive Tests
- Unit tests for service layer
- Integration tests for full API flow
- Mock external dependencies
- Test all error scenarios
- Aim for 80%+ code coverage

### Step 8: Document API
- Generate OpenAPI/Swagger documentation
- Document authentication method
- Provide example requests and responses
- Include error code reference

## Code Example: FastAPI Authentication Endpoints

```python
# routes/auth.py
from datetime import datetime, timedelta, timezone
from typing import Optional

from fastapi import APIRouter, HTTPException, status, Depends
from pydantic import BaseModel, EmailStr, Field
from sqlalchemy.orm import Session
from passlib.context import CryptContext
from jose import JWTError, jwt

from db.database import get_db
from models.user import User
from config import settings

router = APIRouter(prefix="/api/v1/auth", tags=["authentication"])

# Password hashing context
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

# ============================================================================
# Request/Response Models with Input Validation
# ============================================================================

class RegisterRequest(BaseModel):
    """User registration request with comprehensive validation."""
    
    email: EmailStr = Field(..., description="User email address")
    password: str = Field(
        ...,
        min_length=8,
        max_length=128,
        description="Password (8-128 characters, must contain uppercase, lowercase, digit, special char)"
    )
    first_name: str = Field(..., min_length=1, max_length=100)
    last_name: str = Field(..., min_length=1, max_length=100)
    
    class Config:
        json_schema_extra = {
            "example": {
                "email": "user@example.com",
                "password": "SecurePass123!",
                "first_name": "John",
                "last_name": "Doe"
            }
        }


class LoginRequest(BaseModel):
    """User login request."""
    
    email: EmailStr = Field(..., description="User email address")
    password: str = Field(..., description="User password")
    
    class Config:
        json_schema_extra = {
            "example": {
                "email": "user@example.com",
                "password": "SecurePass123!"
            }
        }


class TokenResponse(BaseModel):
    """JWT token response."""
    
    access_token: str = Field(..., description="JWT access token")
    token_type: str = Field(default="bearer", description="Token type")
    expires_in: int = Field(..., description="Token expiration time in seconds")
    
    class Config:
        json_schema_extra = {
            "example": {
                "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
                "token_type": "bearer",
                "expires_in": 3600
            }
        }


class UserResponse(BaseModel):
    """User response model (safe - no password)."""
    
    id: int
    email: str
    first_name: str
    last_name: str
    created_at: datetime
    
    class Config:
        from_attributes = True
        json_schema_extra = {
            "example": {
                "id": 1,
                "email": "user@example.com",
                "first_name": "John",
                "last_name": "Doe",
                "created_at": "2025-05-20T10:30:00Z"
            }
        }


# ============================================================================
# Helper Functions
# ============================================================================

def hash_password(password: str) -> str:
    """Hash password using bcrypt."""
    return pwd_context.hash(password)


def verify_password(plain_password: str, hashed_password: str) -> bool:
    """Verify password against hash."""
    return pwd_context.verify(plain_password, hashed_password)


def create_access_token(
    data: dict,
    expires_delta: Optional[timedelta] = None
) -> tuple[str, int]:
    """
    Create JWT access token.
    
    Args:
        data: Claims to include in token
        expires_delta: Token expiration time (default: 1 hour)
    
    Returns:
        Tuple of (token, expires_in_seconds)
    
    Raises:
        ValueError: If secret key is not configured
    """
    if not settings.SECRET_KEY:
        raise ValueError("SECRET_KEY not configured")
    
    to_encode = data.copy()
    
    if expires_delta:
        expire = datetime.now(timezone.utc) + expires_delta
    else:
        expire = datetime.now(timezone.utc) + timedelta(hours=1)
    
    to_encode.update({"exp": expire})
    
    encoded_jwt = jwt.encode(
        to_encode,
        settings.SECRET_KEY,
        algorithm=settings.ALGORITHM
    )
    
    expires_in = int(expires_delta.total_seconds()) if expires_delta else 3600
    
    return encoded_jwt, expires_in


def get_user_by_email(db: Session, email: str) -> Optional[User]:
    """Get user from database by email."""
    return db.query(User).filter(User.email == email).first()


# ============================================================================
# Endpoints
# ============================================================================

@router.post(
    "/register",
    response_model=UserResponse,
    status_code=status.HTTP_201_CREATED,
    summary="Register a new user",
    responses={
        201: {"description": "User registered successfully"},
        400: {"description": "Invalid input data"},
        409: {"description": "Email already registered"},
        500: {"description": "Internal server error"}
    }
)
async def register(
    request: RegisterRequest,
    db: Session = Depends(get_db)
) -> UserResponse:
    """
    Register a new user account.
    
    - **email**: Must be a valid email address and unique
    - **password**: Must be 8+ characters with uppercase, lowercase, digit, and special character
    - **first_name**: Required, 1-100 characters
    - **last_name**: Required, 1-100 characters
    
    Returns: Created user object (without password)
    
    Raises:
        HTTPException 409: Email already registered
        HTTPException 400: Invalid input validation failed
        HTTPException 500: Database error
    """
    # Check if user already exists
    existing_user = get_user_by_email(db, request.email)
    if existing_user:
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail=f"Email '{request.email}' is already registered",
            headers={"X-Error-Code": "EMAIL_EXISTS"}
        )
    
    # Validate password strength
    if not _is_strong_password(request.password):
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Password must contain uppercase, lowercase, digit, and special character",
            headers={"X-Error-Code": "WEAK_PASSWORD"}
        )
    
    # Create new user
    hashed_password = hash_password(request.password)
    new_user = User(
        email=request.email,
        password_hash=hashed_password,
        first_name=request.first_name,
        last_name=request.last_name,
        created_at=datetime.now(timezone.utc)
    )
    
    try:
        db.add(new_user)
        db.commit()
        db.refresh(new_user)
    except Exception as e:
        db.rollback()
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail="Failed to create user account",
            headers={"X-Error-Code": "DB_ERROR"}
        ) from e
    
    return UserResponse.model_validate(new_user)


@router.post(
    "/login",
    response_model=TokenResponse,
    status_code=status.HTTP_200_OK,
    summary="User login",
    responses={
        200: {"description": "Login successful, token returned"},
        401: {"description": "Invalid credentials"},
        400: {"description": "Invalid input"},
        500: {"description": "Internal server error"}
    }
)
async def login(
    request: LoginRequest,
    db: Session = Depends(get_db)
) -> TokenResponse:
    """
    Authenticate user and return JWT access token.
    
    - **email**: User email address
    - **password**: User password
    
    Returns: JWT access token valid for 1 hour
    
    Raises:
        HTTPException 401: Invalid email or password
        HTTPException 400: Invalid input data
        HTTPException 500: Database or token generation error
    """
    # Find user by email
    user = get_user_by_email(db, request.email)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid email or password",
            headers={"X-Error-Code": "INVALID_CREDENTIALS", "WWW-Authenticate": "Bearer"}
        )
    
    # Verify password
    if not verify_password(request.password, user.password_hash):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid email or password",
            headers={"X-Error-Code": "INVALID_CREDENTIALS", "WWW-Authenticate": "Bearer"}
        )
    
    # Create JWT token
    try:
        token_data = {
            "sub": str(user.id),
            "email": user.email,
            "iat": datetime.now(timezone.utc)
        }
        access_token, expires_in = create_access_token(token_data)
    except ValueError as e:
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail="Failed to generate authentication token",
            headers={"X-Error-Code": "TOKEN_ERROR"}
        ) from e
    
    return TokenResponse(
        access_token=access_token,
        token_type="bearer",
        expires_in=expires_in
    )


# ============================================================================
# Helper Functions (continued)
# ============================================================================

def _is_strong_password(password: str) -> bool:
    """
    Validate password strength.
    
    Requirements:
    - Minimum 8 characters
    - At least one uppercase letter
    - At least one lowercase letter
    - At least one digit
    - At least one special character
    
    Args:
        password: Password to validate
    
    Returns:
        True if password meets all requirements
    """
    import re
    
    if len(password) < 8:
        return False
    if not re.search(r"[A-Z]", password):
        return False
    if not re.search(r"[a-z]", password):
        return False
    if not re.search(r"\d", password):
        return False
    if not re.search(r"[!@#$%^&*()_+\-=\[\]{};:,.<>?]", password):
        return False
    
    return True
```

## Validation Checklist

### Endpoint Implementation
- [ ] All endpoints implemented with correct HTTP methods (GET, POST, PUT, DELETE, PATCH)
- [ ] Routes follow RESTful conventions: `/api/v1/{resource}` format
- [ ] Query parameters extracted and validated
- [ ] Path parameters validated and type-checked
- [ ] Response serialization models defined (Pydantic/DTO)

### Input Validation
- [ ] Request models use Pydantic BaseModel (Python) or Bean Validation (Java)
- [ ] Field constraints defined: min/max length, regex patterns, required fields
- [ ] Email validation using EmailStr or custom validator
- [ ] Password validation enforces strength requirements (8+ chars, uppercase, lowercase, digit, special)
- [ ] Numeric ranges validated (positive, non-zero where applicable)
- [ ] Enum constraints for categorical fields
- [ ] Custom validators implemented for complex business rules

### HTTP Status Codes
- [ ] `200 OK` for successful GET, PUT, PATCH requests
- [ ] `201 Created` for successful POST requests (create)
- [ ] `204 No Content` for successful DELETE requests
- [ ] `400 Bad Request` for invalid input (validation errors)
- [ ] `401 Unauthorized` for missing/invalid authentication
- [ ] `403 Forbidden` for insufficient permissions
- [ ] `404 Not Found` for missing resources
- [ ] `409 Conflict` for duplicate resources (email already registered)
- [ ] `500 Internal Server Error` for unexpected server errors

### JWT Token Handling
- [ ] Token generation with proper claims (sub, email, iat, exp)
- [ ] Token expiration set (1 hour standard)
- [ ] Token signature verification on protected routes
- [ ] Refresh token mechanism (optional but recommended)
- [ ] Token rotation on sensitive operations
- [ ] Secure Secret key storage (environment variable, never hardcoded)

### Password Security
- [ ] Password hashing using bcrypt (passlib in Python, spring-security in Java)
- [ ] Password never stored in plain text
- [ ] Password never logged or returned in API responses
- [ ] Hashing uses appropriate work factors (bcrypt cost factor 12+)
- [ ] Password verification uses constant-time comparison

### Configuration & Secrets
- [ ] SECRET_KEY stored in environment variables, not in code
- [ ] Database credentials in environment variables
- [ ] JWT algorithm configured (HS256, RS256, etc.)
- [ ] CORS settings configured for frontend access
- [ ] Rate limiting configured for authentication endpoints

### Code Conventions (from python_advanced_skill/java_advanced_skill)
- [ ] Type hints on all function parameters and return types (Python)
- [ ] Docstrings on all public functions (Python) or JavaDoc (Java)
- [ ] Meaningful variable names (no single letters except loop counters)
- [ ] Functions ≤ 20 lines (single responsibility)
- [ ] Classes ≤ 300 lines (separation of concerns)
- [ ] DRY principle: no code duplication
- [ ] Proper exception handling with custom exceptions

### Error Handling
- [ ] All endpoints have try-catch (Python) or try-except (Java) blocks
- [ ] HTTPException used with meaningful messages and error codes
- [ ] Validation errors return 400 with field-level details
- [ ] Authentication errors return 401 with WWW-Authenticate header
- [ ] Duplicate resource errors return 409 with conflict explanation
- [ ] No sensitive data in error messages (e.g., "User not found" instead of database query)
- [ ] Database errors caught and translated to 500 with generic message

## Success Criteria

### Test Coverage
- [ ] **Unit tests**: 80%+ code coverage for service layer
- [ ] **Integration tests**: All API endpoints tested end-to-end
- [ ] **Authentication tests**: JWT validation, token expiration, invalid credentials
- [ ] **Validation tests**: All field validators tested with valid/invalid inputs
- [ ] **Error tests**: All error scenarios return correct status codes
- [ ] **Test naming**: Follow `test_givenXxx_whenYyy_thenZzz()` pattern
- [ ] **Test structure**: Arrange-Act-Assert (AAA) pattern used

### JWT Token Validation
- [ ] Tokens issued with correct claims and expiration
- [ ] Protected endpoints verify token presence and validity
- [ ] Expired tokens rejected with 401
- [ ] Invalid signatures rejected with 401
- [ ] Token claims (sub, email) validated for authorization decisions

### Error Handling Validation
- [ ] All error scenarios tested: validation failure, duplicate, not found, unauthorized
- [ ] Error responses include consistent format: `{"detail": "message", "code": "ERROR_CODE"}`
- [ ] Proper HTTP status codes returned (400, 401, 403, 404, 409, 500)
- [ ] No stack traces or database details exposed in error messages
- [ ] Sensitive operations (login failures) return generic "Invalid credentials"

### Security Validation
- [ ] Passwords hashed with bcrypt (never plaintext)
- [ ] Password strength enforced (8+ chars, mixed case, digit, special char)
- [ ] No sensitive data in logs (no passwords, tokens, API keys)
- [ ] HTTPS required for all endpoints (configured in deployment)
- [ ] CORS properly configured to prevent cross-origin abuse

### Code Quality Validation
- [ ] All functions ≤ 20 lines, all classes ≤ 300 lines
- [ ] Type hints on all function signatures
- [ ] Docstrings on all public functions
- [ ] No code duplication (DRY principle)
- [ ] Meaningful variable names throughout
- [ ] Proper separation of concerns (routes, services, models)

## Internal Calls

This skill directly leverages:

### From `python_advanced_skill`
- **Type hints**: Use on all function parameters and returns (Python FastAPI implementation)
- **Docstring standards**: Comprehensive docstrings on all public functions
- **Exception handling**: Custom exceptions and proper error propagation
- **Code organization**: Service layer pattern with separation of concerns
- **Testing patterns**: Unit tests with AAA (Arrange-Act-Assert), meaningful test names
- **PEP 8 compliance**: Naming conventions, import organization, line lengths

### From `java_advanced_skill`
- **Spring Boot patterns**: Controller-Service-Repository architecture (Java implementation)
- **Bean validation**: @Valid, @NotNull, @Email, custom validators
- **Exception handling**: Custom exceptions extending RuntimeException, @ControllerAdvice
- **Transaction management**: @Transactional for database operations
- **Testing patterns**: Unit/integration tests with Mockito, meaningful test names
- **JavaDoc standards**: Comprehensive JavaDoc on all public classes/methods

## Related Skills

- `code_health_skill.md` - Code quality, error handling, performance patterns
- `error_handling_skill.md` - Comprehensive error handling strategies
- `python_advanced_skill.md` - Python coding standards and patterns
- `java_advanced_skill.md` - Java coding standards and patterns
- `documentation_skill.md` - API documentation and examples
- `logger_skill.md` - Logging standards and practices

## Version History

### v1.0 (2025-05-20)
- Initial release
- FastAPI authentication endpoints (register, login)
- JWT token generation and validation
- Input validation with Pydantic
- Password hashing with bcrypt
- Comprehensive error handling
- Full validation checklist and success criteria