DevCorner2

Posted on May 22

📘 FastAPI In-Depth Documentation

Introduction to FastAPI
Project Setup
Folder Structure (Production Grade)
Basic FastAPI Application
Path Parameters, Query Parameters, and Request Bodies
Pydantic Models for Data Validation
CRUD with SQL Databases (MySQL/MariaDB)
Dependency Injection
Exception Handling
Standardized Response Structure
Authentication & Authorization
Testing FastAPI Applications
Running in Production
Documentation & OpenAPI
Conclusion

1. 📌 Introduction to FastAPI

FastAPI is a modern, high-performance, Python web framework for building APIs with:

Type hints
Automatic validation
Auto-generated Swagger UI
ASGI (async support)

2. ⚙️ Project Setup

📦 Install FastAPI and Uvicorn

pip install fastapi uvicorn

For MySQL support:

pip install sqlalchemy pymysql alembic

3. 🗂 Folder Structure (Production Grade)

app/
├── api/
│   ├── routes/
│   │   └── user.py
│   └── dependencies.py
├── core/
│   ├── config.py
│   └── security.py
├── db/
│   ├── base.py
│   ├── session.py
│   └── models/
│       └── user.py
│   └── crud/
│       └── user.py
├── schemas/
│   └── user.py
├── services/
│   └── user_service.py
├── main.py
└── exceptions/
    └── handlers.py

4. 🧱 Basic FastAPI Application

main.py:

from fastapi import FastAPI
from app.api.routes import user
from app.exceptions.handlers import add_exception_handlers

app = FastAPI(title="FastAPI CRUD App")

app.include_router(user.router, prefix="/api/v1/users")

add_exception_handlers(app)

5. 📥 Handling Parameters

from fastapi import FastAPI, Query, Path

@app.get("/items/{item_id}")
def read_item(item_id: int = Path(...), q: str = Query(None)):
    return {"item_id": item_id, "q": q}

6. 📐 Pydantic Models

schemas/user.py

from pydantic import BaseModel, EmailStr

class UserCreate(BaseModel):
    name: str
    email: EmailStr
    password: str

class UserRead(BaseModel):
    id: int
    name: str
    email: EmailStr

    class Config:
        orm_mode = True

7. 🗃️ CRUD with SQLAlchemy

db/session.py

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "mysql+pymysql://user:password@localhost/dbname"

engine = create_engine(DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

db/models/user.py

from sqlalchemy import Column, Integer, String
from app.db.base import Base

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String(50))
    email = Column(String(100), unique=True, index=True)
    password = Column(String(100))

db/base.py

from sqlalchemy.ext.declarative import declarative_base
Base = declarative_base()

db/crud/user.py

from sqlalchemy.orm import Session
from app.db.models.user import User
from app.schemas.user import UserCreate

def create_user(db: Session, user: UserCreate):
    db_user = User(**user.dict())
    db.add(db_user)
    db.commit()
    db.refresh(db_user)
    return db_user

def get_users(db: Session, skip: int = 0, limit: int = 10):
    return db.query(User).offset(skip).limit(limit).all()

8. 🧩 Dependency Injection

api/dependencies.py

from app.db.session import SessionLocal
from fastapi import Depends

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

9. ❗ Exception Handling

exceptions/handlers.py

from fastapi import Request, FastAPI
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError

def add_exception_handlers(app: FastAPI):
    @app.exception_handler(RequestValidationError)
    async def validation_exception_handler(request: Request, exc: RequestValidationError):
        return JSONResponse(
            status_code=422,
            content={"detail": exc.errors(), "body": exc.body},
        )

    @app.exception_handler(Exception)
    async def general_exception_handler(request: Request, exc: Exception):
        return JSONResponse(
            status_code=500,
            content={"message": "Internal server error"},
        )

10. 📦 Standardized Response Structure

Use a common response model:

from pydantic import BaseModel
from typing import Generic, TypeVar, Optional

T = TypeVar("T")

class ResponseModel(BaseModel, Generic[T]):
    success: bool
    message: str
    data: Optional[T] = None

Use it in endpoints:

@app.post("/", response_model=ResponseModel[UserRead])
def create(user: UserCreate, db: Session = Depends(get_db)):
    new_user = crud.create_user(db, user)
    return ResponseModel(success=True, message="User created", data=new_user)

11. 🔐 Authentication & Authorization

core/security.py:

from passlib.context import CryptContext
from jose import jwt

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
SECRET_KEY = "your-secret-key"
ALGORITHM = "HS256"

def hash_password(password: str):
    return pwd_context.hash(password)

def verify_password(plain_password, hashed_password):
    return pwd_context.verify(plain_password, hashed_password)

def create_access_token(data: dict):
    return jwt.encode(data, SECRET_KEY, algorithm=ALGORITHM)

Use OAuth2PasswordBearer from fastapi.security.

12. 🧪 Testing FastAPI Applications

test_main.py:

from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_create_user():
    response = client.post("/api/v1/users", json={"name": "Test", "email": "test@example.com", "password": "123456"})
    assert response.status_code == 200
    assert response.json()["data"]["email"] == "test@example.com"

13. 🚀 Running in Production

Use Uvicorn with Gunicorn:

pip install gunicorn
gunicorn -w 4 -k uvicorn.workers.UvicornWorker app.main:app

Use environment variables, .env, and tools like python-dotenv.

14. 📃 Documentation & OpenAPI

FastAPI automatically generates:

/docs — Swagger UI
/redoc — ReDoc
/openapi.json — OpenAPI schema

Customize via:

FastAPI(
    title="My App",
    description="API for My Application",
    version="1.0.0",
    docs_url="/documentation",
    redoc_url=None
)

15. ✅ Conclusion

FastAPI is a production-ready, robust, and efficient Python web framework that scales well with modern microservice-based and async-first architectures.