Detailed Explanation of FastAPI’s dependencies.py

FastAPI utilizes Dependency Injection (DI) to enhance code reusability and maintainability.
dependencies.py is a dedicated file for managing these dependencies.

In this article, we will explain the role of dependencies.py, common usage patterns, and design considerations in detail.

1. Role of dependencies.py

In FastAPI, dependencies are common processes that are used across multiple request handlers.
By defining them as functions, they can be easily reused in API endpoints.

Typical use cases include:

• Database session management
• Authentication and authorization
• Processing common request headers
• Fetching configuration settings
• Handling caching and logging

By consolidating common logic in dependencies.py, we can separate concerns and keep API endpoint definitions simple.

2. Basic Structure of dependencies.py

Managing Database Sessions

To manage database connections, we define a dependency that creates and closes a session per request.

dependencies.py

from sqlalchemy.orm import Session
from fastapi import Depends
from app.database import SessionLocal

def get_db():
    """Dependency to obtain a database session"""
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

Using yield, the session is automatically managed and closed when the request is completed.

Usage Example (routers/user.py)

from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session
from app.dependencies import get_db
from app.models.user import User

router = APIRouter()

@router.get("/users/")
def read_users(db: Session = Depends(get_db)):
    return db.query(User).all()

✅ Key Points

• db: Session = Depends(get_db) injects the database session.
• The session is automatically closed after use.

3. Separating Authentication & Authorization in dependencies.py

FastAPI allows authentication (e.g., JWT tokens) to be managed as dependencies, improving security.

Authentication Dependency

from fastapi import Depends, HTTPException, Security
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

def get_current_user(token: str = Depends(oauth2_scheme)):
    """Validate JWT token and retrieve user information"""
    if not token or token != "valid_token":  # Token validation logic required
        raise HTTPException(status_code=401, detail="Invalid token")
    return {"username": "test_user"}

Usage Example (routers/protected.py)

from fastapi import APIRouter, Depends
from app.dependencies import get_current_user

router = APIRouter()

@router.get("/protected/")
def protected_route(user: dict = Depends(get_current_user)):
    return {"message": f"Hello {user['username']}!"}

✅ Key Points

• Depends(get_current_user) retrieves the authenticated user.
• Invalid tokens return 401 Unauthorized.

4. Managing Configuration Settings in dependencies.py

Application settings (e.g., environment variables) are best managed within dependencies.py.

Fetching Environment Variables

from pydantic import BaseSettings

class Settings(BaseSettings):
    database_url: str
    secret_key: str

    class Config:
        env_file = ".env"

settings = Settings()

Usage Example

from fastapi import Depends
from app.dependencies import settings

def get_secret_key(settings: Settings = Depends(lambda: settings)):
    return settings.secret_key

➡️ API endpoints can use Depends(get_secret_key) to access configuration values.

5. Processing Common Request Headers in dependencies.py

If an API expects clients to send specific request headers (e.g., X-API-Key), a dependency can be used.

Dependency to Validate API Key

from fastapi import Header, HTTPException

def get_api_key(x_api_key: str = Header(None)):
    if x_api_key != "expected_api_key":
        raise HTTPException(status_code=403, detail="Invalid API Key")
    return x_api_key

Usage Example

from fastapi import APIRouter, Depends
from app.dependencies import get_api_key

router = APIRouter()

@router.get("/secure-data/")
def secure_endpoint(api_key: str = Depends(get_api_key)):
    return {"message": "Access granted"}

✅ Key Points

• Depends(get_api_key) automatically checks the API key.
• Invalid keys return 403 Forbidden.

6. Best Practices for dependencies.py Design

✅ Consolidate Common Logic in dependencies.py

• Database session management
• Authentication & authorization
• Fetching configuration settings
• Common request processing (headers, logging, etc.)

✅ Use get_ Prefix for Clarity

• Use function names like get_db(), get_current_user(), etc., for better readability.

✅ Ensure Proper Resource Management

• Use yield to manage resources like database sessions.

✅ Improve API Endpoint Readability

• By defining dependencies separately, API endpoint definitions remain clean.

7. Summary

• dependencies.py manages dependencies efficiently in FastAPI.
• Common logic such as database sessions, authentication, and request headers can be centralized.
• Using Depends() in API endpoints improves readability and maintainability.
• Proper dependency design enables scalable and maintainable APIs.

By leveraging dependencies.py, you can build a cleaner, more maintainable FastAPI application! 🚀