corpus/fastapi_docs.md

FastAPI — Complete Documentation Reference

Source: https://fastapi.tiangolo.com/

---

What is FastAPI?

FastAPI is a modern, high-performance web framework for building APIs with Python 3.8+, based on standard Python type hints. It was created by Sebastián Ramírez and is one of the fastest Python frameworks available, on par with NodeJS and Go (thanks to Starlette and Pydantic).

FastAPI is used in production at companies like Microsoft, Uber, Netflix, and NASA.

Key Characteristics

• Fast to run: Very high performance, on par with NodeJS and Go.
• Fast to code: Increases development speed by 200–300%.
• Fewer bugs: Reduces developer-induced errors by ~40%.
• Intuitive: Great editor support with autocompletion everywhere.
• Easy: Designed to be easy to use and learn.
• Short: Minimize code duplication.
• Robust: Get production-ready code with automatic interactive documentation.
• Standards-based: Based on (and fully compatible with) the open standards OpenAPI and JSON Schema.

---

Installation

pip install fastapi
pip install "uvicorn[standard]"  # ASGI server to run FastAPI

---

First Steps — Hello World

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

Run with:

uvicorn main:app --reload

Visit: http://127.0.0.1:8000/ — returns JSON response. Visit: http://127.0.0.1:8000/docs — Swagger UI auto-generated docs. Visit: http://127.0.0.1:8000/redoc — ReDoc auto-generated docs.

---

Path Parameters

FastAPI uses Python type hints to declare path parameters:

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

FastAPI automatically:

• Validates that item_id is an integer.
• Returns a clear error if validation fails.
• Documents the parameter in OpenAPI schema.

Predefined values with Enum

from enum import Enum

class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"

@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    return {"model_name": model_name}

---

Query Parameters

Parameters not in the path become query parameters:

fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}]

@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

• URL: /items/?skip=0&limit=10
• Optional parameters with defaults: limit: int = 10
• Optional parameters without value: q: str | None = None

---

Request Body

Use Pydantic models to declare request bodies:

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None

@app.post("/items/")
async def create_item(item: Item):
    return item

FastAPI will:

• Read the request body as JSON.
• Convert it to the Item model.
• Validate the data.
• Provide the data in the function parameter item.
• Generate JSON Schema documentation.

---

Response Model

Control what is returned to the client:

class ItemOut(BaseModel):
    name: str
    price: float

@app.post("/items/", response_model=ItemOut)
async def create_item(item: Item):
    return item

This filters the output to only include fields declared in ItemOut, even if the input model has more fields.

---

HTTP Methods

FastAPI supports all HTTP methods:

@app.get("/items/")       # GET
@app.post("/items/")      # POST
@app.put("/items/{id}")   # PUT
@app.delete("/items/{id}")# DELETE
@app.patch("/items/{id}") # PATCH
@app.options("/items/")   # OPTIONS
@app.head("/items/")      # HEAD

---

Status Codes

from fastapi import status

@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(item: Item):
    return item

Common status codes:

• 200 — OK (default for GET)
• 201 — Created (for POST)
• 204 — No Content (for DELETE)
• 400 — Bad Request
• 401 — Unauthorized
• 403 — Forbidden
• 404 — Not Found
• 422 — Unprocessable Entity (validation errors)
• 500 — Internal Server Error

---

Request Headers and Cookies

from fastapi import Header, Cookie

@app.get("/items/")
async def read_items(user_agent: str | None = Header(default=None)):
    return {"User-Agent": user_agent}

@app.get("/cookie/")
async def read_cookie(ads_id: str | None = Cookie(default=None)):
    return {"ads_id": ads_id}

---

Form Data and File Uploads

from fastapi import Form, File, UploadFile

@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
    return {"username": username}

@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    return {"filename": file.filename}

---

Dependencies Injection

FastAPI has a powerful dependency injection system:

from fastapi import Depends

async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit}

@app.get("/items/")
async def read_items(commons: dict = Depends(common_parameters)):
    return commons

Class-based dependencies

class CommonQueryParams:
    def __init__(self, q: str | None = None, skip: int = 0, limit: int = 100):
        self.q = q
        self.skip = skip
        self.limit = limit

@app.get("/items/")
async def read_items(commons: CommonQueryParams = Depends()):
    return {"q": commons.q, "skip": commons.skip}

Dependency with yield (for database sessions)

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

@app.get("/items/")
async def read_items(db: Session = Depends(get_db)):
    return db.query(Item).all()

---

Security and Authentication

OAuth2 with Password Bearer

from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.post("/token")
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
    # validate user, return JWT
    return {"access_token": "...", "token_type": "bearer"}

@app.get("/users/me")
async def read_users_me(token: str = Depends(oauth2_scheme)):
    return {"token": token}

API Key Header

from fastapi.security import APIKeyHeader

api_key_header = APIKeyHeader(name="X-API-Key")

@app.get("/secure/")
async def secure_endpoint(api_key: str = Depends(api_key_header)):
    return {"api_key": api_key}

---

Middleware

Middleware runs before and after each request:

from fastapi.middleware.cors import CORSMiddleware
import time

@app.middleware("http")
async def add_process_time_header(request, call_next):
    start_time = time.time()
    response = await call_next(request)
    process_time = time.time() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response

# CORS Middleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

---

Background Tasks

from fastapi import BackgroundTasks

def write_notification(email: str, message: str = ""):
    with open("log.txt", mode="a") as f:
        f.write(f"notification for {email}: {message}\n")

@app.post("/send-notification/{email}")
async def send_notification(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(write_notification, email, message="some notification")
    return {"message": "Notification sent in the background"}

---

Exception Handling

from fastapi import HTTPException
from fastapi.responses import JSONResponse
from fastapi.requests import Request

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item": items[item_id]}

# Custom exception handler
@app.exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
    return JSONResponse(status_code=400, content={"message": str(exc)})

---

Routers — Organizing Large Applications

# routers/items.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/items/")
async def read_items():
    return [{"item_id": "Foo"}]

# main.py
from fastapi import FastAPI
from .routers import items

app = FastAPI()
app.include_router(items.router, prefix="/api/v1", tags=["items"])

---

FastAPI vs Flask vs Django

Feature	FastAPI	Flask	Django
Performance	Very high (ASGI)	Medium (WSGI)	Medium (WSGI)
Async support	Native	Limited	Limited
Data validation	Built-in (Pydantic)	Manual	Forms/Serializers
Auto docs	Yes (Swagger + ReDoc)	No	No
Type hints	Full support	Partial	Partial
ORM	Any	Any	Django ORM
Learning curve	Low	Very Low	High
Best for	APIs, microservices	Simple apps	Full-stack web

---

FastAPI with Databases

SQLAlchemy (sync)

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

SQLALCHEMY_DATABASE_URL = "sqlite:///./sql_app.db"
engine = create_engine(SQLALCHEMY_DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

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

Async with asyncpg / SQLAlchemy async

from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession

DATABASE_URL = "postgresql+asyncpg://user:password@localhost/dbname"
engine = create_async_engine(DATABASE_URL)

---

Testing FastAPI

from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_read_main():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello World"}

---

Deployment

With Uvicorn

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

With Gunicorn + Uvicorn workers

gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Docker

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

---

FastAPI Dependencies — Common Use Cases

1. Database sessions — yield pattern with cleanup
2. Authentication — OAuth2, JWT, API keys
3. Rate limiting — count requests per user
4. Caching — Redis-based response caching
5. Feature flags — conditionally enable endpoints
6. Audit logging — log all API access
7. Pagination — standard skip/limit across all endpoints