FastAPI Backend Development

Overview

This skill provides comprehensive guidance for building modern, production-ready FastAPI backend applications. Covers async/await patterns, database session management with async SQLAlchemy, JWT and OAuth2 authentication, Pydantic model validation, OpenAPI documentation, error handling patterns, and background task processing with Celery.

When to Use This Skill

Use this skill when:

• Building a new FastAPI backend application from scratch
• Implementing CRUD endpoints with async database operations
• Setting up JWT or OAuth2 authentication
• Configuring async SQLAlchemy session management
• Creating Pydantic models with complex validation
• Implementing background tasks with Celery
• Setting up proper error handling and logging
• Building RESTful APIs with OpenAPI documentation

Quick Start with Project Template

For new projects, use the complete FastAPI project template available in assets/project-template/. This template includes:

• Complete application structure with async/await throughout
• JWT authentication with access and refresh tokens
• Async SQLAlchemy 2.0 configuration
• User model and CRUD operations
• Pydantic schemas for request/response validation
• Docker Compose setup with PostgreSQL, Redis, and Celery
• Alembic migrations configuration
• Environment-based configuration with Pydantic Settings
• OpenAPI documentation

To use the template:

1. Copy the entire assets/project-template/ directory to the project location
2. Create .env file from .env.example and configure settings
3. Install dependencies: pip install -r requirements.txt
4. Run with Docker Compose: docker-compose up

Core Development Tasks

1. CRUD Operations with Async/Await

For implementing CRUD endpoints, refer to scripts/crud_template.py which provides a generic, type-safe CRUD base class.

Key patterns:

• Use Generic types for type safety: CRUDBase[ModelType, CreateSchemaType, UpdateSchemaType]
• Always use async session operations: await db.execute(), await db.commit()
• Implement pagination with skip/limit parameters
• Support optional filtering with dictionary-based filters
• Use scalar_one_or_none() for single results, scalars().all() for lists

Implementation steps:

1. Define SQLAlchemy model in app/models/
2. Create Pydantic schemas in app/schemas/ for Create, Update, and Response
3. Implement CRUD class in app/crud/ inheriting from the template
4. Create API endpoints in app/api/v1/endpoints/
5. Use database session dependency: db: AsyncSession = Depends(get_db)

For detailed patterns and query examples, consult references/patterns.md section "Async/Await Patterns" and references/database.md.

2. JWT Authentication

For authentication implementation, refer to scripts/auth_middleware.py which provides complete JWT authentication utilities.

Key components:

• Password hashing with bcrypt: verify_password(), get_password_hash()
• Token creation: create_access_token(), create_refresh_token()
• OAuth2 password bearer scheme for token validation
• Current user dependency: get_current_user() for protected routes
• Scope-based authorization: require_scopes() factory

Implementation steps:

1. Configure SECRET_KEY and token expiration in settings
2. Implement user authentication in CRUD layer
3. Create login endpoint that returns access and refresh tokens
4. Use get_current_user dependency in protected routes
5. Implement refresh token endpoint for token renewal

For complete authentication flows including OAuth2 integration, consult references/authentication.md.

3. Database Session Management

For database configuration, use the pattern from assets/project-template/app/db/session.py.

Key patterns:

• Create async engine with proper connection pooling
• Use sessionmaker with AsyncSession class
• Implement dependency that handles commit/rollback automatically
• Configure pool size and overflow based on load requirements
• Use pool_pre_ping=True to verify connections before use

Session dependency pattern:

async def get_db() -> AsyncGenerator[AsyncSession, None]:
    async with AsyncSessionLocal() as session:
        try:
            yield session
            await session.commit()
        except Exception:
            await session.rollback()
            raise
        finally:
            await session.close()

For detailed database patterns including transactions, bulk operations, and migrations, consult references/database.md.

4. Pydantic Models and Validation

Create Pydantic schemas for all request and response models.

Schema patterns:

• Base schema with common fields
• Create schema for incoming data (excludes id, timestamps)
• Update schema with all fields optional
• Response schema that matches database model
• Use model_config = ConfigDict(from_attributes=True) for ORM mode

Validation features:

• Use EmailStr for email validation
• Custom validators with @field_validator
• Computed fields with @computed_field
• Model validators with @model_validator
• Constrained types: constr(), conint(), etc.

Refer to project template schemas in assets/project-template/app/schemas/ for examples.

5. API Documentation with OpenAPI

FastAPI automatically generates OpenAPI documentation.

Enhancement patterns:

• Add response models to all endpoints: response_model=UserSchema
• Document error responses: responses={404: {"model": ErrorResponse}}
• Use tags to group endpoints: router = APIRouter(tags=["users"])
• Add descriptions to route decorators
• Include examples in Pydantic models with model_config

Documentation URLs:

• Swagger UI: http://localhost:8000/api/v1/docs
• ReDoc: http://localhost:8000/api/v1/redoc
• OpenAPI JSON: http://localhost:8000/api/v1/openapi.json

6. Error Handling and Logging

For comprehensive error handling patterns, consult references/error_handling.md.

Key patterns:

• Create custom exception classes inheriting from HTTPException
• Implement global exception handlers for common errors
• Use structured logging with loguru
• Add request ID tracking middleware
• Log all errors with context (user ID, request ID, etc.)

Custom exceptions:

• NotFoundException - 404 errors
• BadRequestException - 400 errors
• UnauthorizedException - 401 errors
• ForbiddenException - 403 errors
• ConflictException - 409 errors

Logging setup:

• Configure loguru with console and file outputs
• Intercept standard logging to route through loguru
• Set appropriate log levels for third-party libraries
• Include request/response logging middleware
• Use log rotation and retention policies

7. Background Tasks with Celery

For background task implementation, refer to scripts/celery_task_example.py.

Task patterns:

• Simple async tasks: @celery_app.task(name="task_name")
• Tasks with retry logic: @celery_app.task(bind=True, max_retries=3)
• Task chaining: Use chain() to link tasks
• Periodic tasks: Configure with @celery_app.on_after_configure.connect
• Task monitoring: Track task status with AsyncResult

When to use Celery vs FastAPI BackgroundTasks:

• Use FastAPI BackgroundTasks for lightweight, fast operations (email notifications, logging)
• Use Celery for long-running, resource-intensive, or scheduled tasks (report generation, data processing)

Integration with FastAPI:

1. Create Celery app with Redis broker
2. Define tasks in separate module
3. Trigger tasks from endpoints: task.delay(params)
4. Provide endpoint to check task status
5. Run Celery worker: celery -A app.tasks worker

Project Structure Best Practices

Follow the structure from the project template:

app/
├── main.py                 # Application entry point, middleware, CORS
├── core/
│   ├── config.py          # Pydantic Settings configuration
│   ├── security.py        # JWT, password hashing utilities
│   └── deps.py            # Common dependencies (DB session, current user)
├── api/
│   └── v1/
│       ├── api.py         # Router aggregation
│       └── endpoints/     # Individual route modules
├── models/                # SQLAlchemy ORM models
├── schemas/               # Pydantic request/response schemas
├── crud/                  # Database operations (separated from routes)
├── db/
│   ├── session.py         # Database engine and session factory
│   └── base.py            # Import all models for Alembic
└── utils/                 # Utility functions

Advanced Patterns

API Versioning

Version APIs using router prefixes (/api/v1, /api/v2) to maintain backward compatibility when introducing breaking changes.

Pagination

Implement standard pagination with skip/limit parameters and return total count for client-side pagination controls.

Filtering and Searching

Support complex filters using SQLAlchemy's or_(), and_(), and .ilike() for case-insensitive searches.

Relationships and Eager Loading

Use selectinload() for one-to-many relationships and joinedload() for many-to-one to avoid N+1 queries.

Transactions

Wrap related database operations in transactions using async with db.begin() or the session dependency's automatic handling.

Testing

Write async tests using pytest-asyncio with in-memory SQLite database for fast test execution.

Resources

scripts/

Reusable code templates for common patterns:

• crud_template.py - Generic CRUD base class with full typing support
• auth_middleware.py - Complete JWT authentication implementation
• celery_task_example.py - Background task patterns and Celery configuration

These scripts can be copied directly into projects or used as reference implementations.

references/

Comprehensive documentation for advanced patterns:

• patterns.md - FastAPI best practices, async patterns, dependency injection, response models, pagination, background tasks, API versioning, configuration management, and testing
• database.md - Async SQLAlchemy setup, model definition, query patterns, relationships, transactions, bulk operations, Alembic migrations, and connection pooling
• authentication.md - JWT authentication flow, OAuth2 implementation, scope-based authorization, third-party OAuth (Google, GitHub), API key authentication, and security best practices
• error_handling.md - Custom exceptions, global exception handlers, error response models, structured logging with loguru, request ID tracking, health checks, and Sentry integration

Load these references when implementing specific features or troubleshooting issues.

assets/

Complete project boilerplate:

• project-template/ - Production-ready FastAPI project with all components configured and integrated, including Docker Compose setup, example models and endpoints, and configuration files

Copy this template to bootstrap new FastAPI projects quickly.