FastAPI Project

---
applyTo: "**/*.py, **/api/**, **/routers/**"
---

# FastAPI Development Instructions (2025)

_Last updated: October 2025_

- Always use the fetch tool to look up the latest FastAPI documentation: https://fastapi.tiangolo.com
- Use FastAPI 0.100+ for building modern Python APIs
- Leverage Pydantic for data validation and serialization
- Implement async/await for I/O-bound operations
- Use dependency injection for shared logic and authentication
- Follow RESTful API design principles

**Core Principles:**

- Use Pydantic models for request/response validation
- Implement async functions for database and external API calls
- Use dependency injection with Depends() for reusable logic
- Leverage automatic OpenAPI (Swagger) documentation
- Implement proper error handling with HTTPException
- Use type hints for automatic validation and documentation

**Project Structure:**

- Organize routers in separate files (users.py, items.py)
- Define Pydantic schemas in schemas/ directory
- Implement database models in models/ directory
- Use dependencies/ for reusable dependencies
- Create main.py as application entry point

**Routing:**

- Use APIRouter for organizing endpoints
- Implement proper HTTP methods (GET, POST, PUT, DELETE, PATCH)
- Use path parameters and query parameters appropriately
- Define response models for documentation and validation
- Use tags for organizing API documentation

**Request/Response:**

- Define Pydantic models for request bodies
- Use response_model for automatic validation
- Implement proper status codes
- Use background tasks for non-blocking operations
- Handle file uploads with UploadFile

**Database:**

- Use SQLAlchemy with async support for databases
- Implement Alembic for database migrations
- Use async session with dependency injection
- Define proper ORM models with relationships
- Implement connection pooling

**Authentication:**

- Use OAuth2 with JWT tokens for authentication
- Implement proper password hashing with bcrypt
- Use dependencies for protecting routes
- Store secrets in environment variables
- Implement refresh token rotation

**Validation:**

- Use Pydantic validators for complex validation
- Implement custom validators with @validator
- Use Field() for additional constraints
- Handle validation errors with proper responses

**Performance:**

- Use async/await for I/O operations
- Implement caching with Redis
- Use background tasks for long-running operations
- Enable compression middleware
- Implement proper database query optimization

**Testing:**

- Use pytest with pytest-asyncio for testing
- Implement TestClient for API testing
- Mock external dependencies
- Test with proper fixtures
- Implement integration tests

**Summary:**

> For all FastAPI work, always use the fetch tool to look up the latest documentation from https://fastapi.tiangolo.com. Build fast, modern, async Python APIs.