Skip to content

FastAPI Spickzettel

Modernes, schnelles Python-Web-Framework zum Bauen von APIs.

01

Einstieg

Erste API

FastAPI baut auf Starlette und Pydantic auf. uvicorn ist der ASGI-Server. --reload aktiviert Auto-Reload während der Entwicklung.

fastapi
# install FastAPI and uvicorn
pip install fastapi uvicorn

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

# run: uvicorn main:app --reload

Mit Uvicorn starten

Die App-Instanz 'main:app' bedeutet Modul 'main', Variable 'app'. --reload nur in der Entwicklung; in Produktion ohne starten und einen Prozess-Manager verwenden.

fastapi
# development with auto-reload
uvicorn main:app --reload

# specify host and port
uvicorn main:app --host 0.0.0.0 --port 8000

# run programmatically
import uvicorn
if __name__ == "__main__":
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

Async-Path-Operations

Path operations lassen sich mit 'def' (läuft im Threadpool) oder 'async def' deklarieren. async def verwenden, wenn die Funktion I/O über async-Bibliotheken macht; blockierende Aufrufe in async def blockieren die Event-Loop.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "hello"}

@app.get("/sync")
def read_sync():
    return {"message": "sync also works"}

# use async when calling async libs (httpx, databases)
@app.get("/data")
async def fetch_data():
    import httpx
    async with httpx.AsyncClient() as client:
        r = await client.get("https://api.example.com")
    return r.json()

Path-Operation-Decoratoren

FastAPI unterstützt alle HTTP-Methoden: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD. Jede mappt auf einen Decorator. status_code= auf dem Decorator überschreibt den Standard-Erfolgsstatus.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/items")
def list_items(): ...

@app.post("/items")
def create_item(): ...

@app.put("/items/{item_id}")
def replace_item(item_id: int): ...

@app.patch("/items/{item_id}")
def update_item(item_id: int): ...

@app.delete("/items/{item_id}")
def delete_item(item_id: int): ...

@app.options("/items")
def options_items(): ...

@app.head("/items")
def head_items(): ...

JSON-Antwort & Status

Ein zurückgegebenes Dict/Liste wird automatisch zu JSON mit 200 konvertiert (oder deinem status_code). Für volle Kontrolle über Status, Header oder Inhalt direkt ein JSONResponse oder Response zurückgeben.

fastapi
from fastapi import FastAPI, status
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/plain")
def plain():
    return {"key": "value"}  # auto JSON, 200 OK

@app.post("/created", status_code=status.HTTP_201_CREATED)
def created():
    return {"id": 1}

@app.get("/custom")
def custom():
    return JSONResponse(
        status_code=418,
        content={"error": "I'm a teapot"},
        headers={"X-Custom": "yes"},
    )

Projektstruktur

Eine wachsende App mit APIRouter in Module aufteilen und über app.include_router() registrieren. Pydantic-Schemas, DB-Setup und Dependencies in eigene Dateien für Wartbarkeit.

fastapi
myapp/
  main.py              # creates the FastAPI app
  routers/
    users.py           # APIRouter for /users
    items.py           # APIRouter for /items
  models/
    schemas.py         # Pydantic models
    database.py        # DB engine & session
  dependencies.py      # shared Depends functions
  tests/
    test_main.py

# main.py
from fastapi import FastAPI
from routers import users, items
app = FastAPI()
app.include_router(users.router)
app.include_router(items.router, prefix="/items")
02

Path-Parameter

Grundlegende Path-Parameter

Werte aus dem Pfad sind Strings, außer man ergänzt eine Typ-Annotation. Der Parametername im Pfad muss exakt dem Funktionsargumentnamen entsprechen.

fastapi
from fastapi import FastAPI

app = FastAPI()

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

# GET /items/42 -> {"item_id": "42"}  (string by default)

Typkonvertierung

Eine Typ-Annotation (int, float, bool, str, Enum) lässt FastAPI den Pfadwert validieren und konvertieren. Ungültige Werte geben eine 422-Antwort mit klarer Fehlermeldung.

fastapi
from fastapi import FastAPI

app = FastAPI()

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

# GET /items/3   -> {"item_id": 3}
# GET /items/abc -> 422 Validation Error (not an integer)

Pfad-Validierung

Path() ergänzt Metadaten und Constraints zu einem Pfadparameter. Numerische Constraints: ge (>=), gt (>), le (<=), lt (<). Pfadparameter sind immer erforderlich, daher kann Path() keinen Default setzen.

fastapi
from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(
    item_id: int = Path(
        title="The ID of the item",
        description="Must be a positive integer",
        ge=1,
        le=1000,
    ),
):
    return {"item_id": item_id}

Numerische Constraints

ge/gt/le/lt auf int- oder float-Pfadparametern erzwingen numerische Bereiche. Kombinierte Constraints geben präzise Grenzwertvalidierung mit automatischen 422-Fehlern.

fastapi
from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/ratio/{value}")
def ratio(
    value: float = Path(gt=0, lt=1),  # 0 < value < 1
):
    return {"value": value}

@app.get("/page/{page}")
def page(
    page: int = Path(ge=1),       # >= 1
    size: int = Path(le=100),     # <= 100
):
    return {"page": page, "size": size}

Routen-Reihenfolge zählt

Routen werden in Deklarations-Reihenfolge gematcht. Konkrete Pfade wie /users/me vor dynamische Muster wie /users/{user_id} deklarieren, sonst überdeckt die dynamische Route die konkrete.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/users/me")
def read_current_user():
    return {"user": "me"}

@app.get("/users/{user_id}")
def read_user(user_id: str):
    return {"user_id": user_id}

# /users/me MUST be declared before /users/{user_id}
# otherwise 'me' would match the {user_id} pattern

Enum-Pfadparameter

Ein Enum-Typ für einen Pfadparameter beschränkt ihn auf vordefinierte Werte und erzeugt ein Enum-Schema in den OpenAPI-Docs. (str, Enum) ableiten, damit Werte als Strings serialisieren.

fastapi
from enum import Enum
from fastapi import FastAPI

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

app = FastAPI()

@app.get("/models/{model_name}")
def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model": model_name, "layers": 5}
    return {"model": model_name}

# GET /models/resnet -> {"model": "resnet"}
03

Query-Parameter

Grundlegende Query-Parameter

Funktionsparameter, die NICHT im Pfad sind, werden Query-Parameter. Ein Default macht sie optional; der Default greift, wenn der Query-Key fehlt.

fastapi
from fastapi import FastAPI

app = FastAPI()

fake_items = [{"item": "a"}, {"item": "b"}, {"item": "c"}]

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

# GET /items?skip=0&limit=2
# GET /items                -> skip=0, limit=10

Optionale Query-Parameter

Optional[str] = None (oder str | None = None auf Python 3.10+) für einen Query-Parameter, der fehlen darf. Erforderliche Parameter haben schlicht keinen Default-Wert.

fastapi
from typing import Optional
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: str, q: Optional[str] = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

# GET /items/1?q=hello
# GET /items/1            (q is None)

Query-Validierung

Query() ergänzt Validierung: min_length/max_length für Strings, ge/gt/le/lt für Zahlen, pattern (Regex) für das String-Format. default= setzt einen Wert und wendet trotzdem Constraints an.

fastapi
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/search")
def search(q: str = Query(min_length=3, max_length=50, pattern="^[a-zA-Z]+$")):
    return {"q": q}

@app.get("/page")
def page(limit: int = Query(default=10, ge=1, le=100)):
    return {"limit": limit}

Boolesche Konvertierung

Bool-Query-Parameter akzeptieren viele truthy Werte: true, 1, yes, on (Groß-/Kleinschreibung egal). Alles andere gilt als false. Ungültige Typen wie ?active=maybe geben 422.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/flags")
def flags(active: bool = False):
    return {"active": active}

# GET /flags?active=true   -> {"active": true}
# GET /flags?active=1      -> {"active": true}
# GET /flags?active=yes    -> {"active": true}
# GET /flags?active=off    -> {"active": false}

Listen-Query-Parameter

Ein List[str]-Parameter akzeptiert denselben Key mehrfach im Query-String. Query(default=[]) für eine leere Liste als Default, oder Query(default=None), um fehlende Werte zuzulassen.

fastapi
from typing import List
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
def list_items(q: List[str] = Query(default=[])):
    return {"q": q}

# GET /items?q=a&q=b&q=c  -> {"q": ["a", "b", "c"]}
# declare default=None to accept a list or null

Erforderliche Query-Parameter

Query(...) (der Ellipsis) deklariert einen erforderlichen Query-Parameter mit Validierungs-Metadaten. Ohne Default und ohne Query(...) ist auch ein plain annotierter Parameter erforderlich.

fastapi
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
def read_item(q: str = Query(...)):
    return {"q": q}

# GET /items?q=hello   -> ok
# GET /items           -> 422 (q is required)
# Query(...) (Ellipsis) marks a parameter as required
04

Request-Body (Pydantic)

BaseModel-Grundlagen

Ein als Funktionsparameter deklarierter Pydantic-BaseModel wird zum JSON-Request-Body. FastAPI validiert die Payload, konvertiert Typen und gibt bei ungültigen Daten 422. Felder mit Default sind optional.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    in_stock: bool = True

app = FastAPI()

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

# POST /items  body: {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5, "in_stock": true}

Feldtypen & Constraints

Field() ergänzt Constraints und Metadaten zu Modell-Attributen: min_length/max_length für Strings, gt/ge/lt/le für Zahlen, default_factory für veränderliche Defaults. model_config mit json_schema_extra ergänzt Beispiele in den Docs.

fastapi
from pydantic import BaseModel, Field
from typing import Optional

class Item(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0, description="must be positive")
    tax: Optional[float] = None
    tags: list[str] = Field(default_factory=list)

    model_config = {
        "json_schema_extra": {
            "examples": [{"name": "Apple", "price": 0.5, "tags": ["fruit"]}]
        }
    }

Verschachtelte Models

Models lassen sich verschachteln: einen weiteren BaseModel als Feldtyp deklarieren. FastAPI validiert die volle verschachtelte Struktur rekursiv, und das erzeugte OpenAPI-Schema spiegelt die verschachtelten Objekte.

fastapi
from pydantic import BaseModel
from typing import Optional

class Image(BaseModel):
    url: str
    name: str

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    image: Optional[Image] = None
    images: list[Image] = []

# valid body:
# {"name": "Phone", "image": {"url": "http://x/a.png", "name": "a"}}

Feld-Validierung

@field_validator (Pydantic v2) ergänzt eigene Validierungslogik pro Feld. ValueError werfen, um Input abzulehnen (FastAPI zeigt es als 422). Den (ggf. transformierten) Wert zurückgeben, um ihn zu behalten.

fastapi
from pydantic import BaseModel, field_validator

class User(BaseModel):
    name: str
    email: str

    @field_validator("email")
    @classmethod
    def email_must_contain_at(cls, v: str) -> str:
        if "@" not in v:
            raise ValueError("must contain @")
        return v.lower()

    @field_validator("name")
    @classmethod
    def name_stripped(cls, v: str) -> str:
        return v.strip()

Optionale & Default-Felder

Ein Feld ist nur erforderlich, wenn es keinen Default hat und nicht Optional ist. Optional[str] = None ist das Standardmuster für ein optionales nullable Feld; ein plain Default wie 0.0 macht ein Feld optional mit diesem Wert.

fastapi
from pydantic import BaseModel
from typing import Optional

class Item(BaseModel):
    name: str                       # required
    description: Optional[str] = None  # optional, defaults to None
    price: float = 0.0              # optional, defaults to 0.0
    tags: list[str] = []            # optional, defaults to empty list

# All of these are valid:
# {"name": "X"}
# {"name": "X", "price": 9.99, "tags": ["a"]}

Body mit Path & Query

Path-, Query- und Body-Parameter koexistieren in einer Operation. FastAPI entscheidet: Pfadparameter, wenn im Pfad; Pydantic-Model (oder Body()) für den Body; sonst Query. Optionaler Body braucht None als Default.

fastapi
from fastapi import FastAPI, Path, Query
from pydantic import BaseModel

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

app = FastAPI()

@app.put("/items/{item_id}")
def update_item(
    item_id: int = Path(ge=1),
    q: Optional[str] = Query(default=None),
    item: Item = None,
):
    result = {"item_id": item_id, **item.model_dump()}
    if q:
        result["q"] = q
    return result
05

Response Model

response_model-Grundlagen

response_model filtert die zurückgegebenen Daten auf die im Model definierten Felder, auch wenn du ein Objekt mit zusätzlichen Feldern zurückgibst. Der Standardweg, um sensible Felder wie Passwörter zu verbergen.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class User(BaseModel):
    username: str
    email: str
    hashed_password: str

class UserOut(BaseModel):
    username: str
    email: str

app = FastAPI()

@app.get("/users/me", response_model=UserOut)
def read_user():
    return User(username="bob", email="[email protected]", hashed_password="secret")

# response: {"username": "bob", "email": "[email protected]"}  (no password)

Felder ausschließen

response_model_include und response_model_exclude erlauben Whitelist/Blacklist von Feldern pro Route, ohne neue Models zu definieren. Eine Menge von Feldnamen übergeben. Sie wirken zusätzlich zum response_model.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    secret: str

app = FastAPI()

@app.get("/items/{id}", response_model=Item, response_model_exclude={"secret"})
def read_item(id: int):
    return {"name": "Apple", "price": 0.5, "secret": "hidden"}

@app.get("/items", response_model=list[Item], response_model_include={"name", "price"})
def list_items():
    return [{"name": "Apple", "price": 0.5, "secret": "x"}]

Listen-Antwort

response_model=list[Model] (oder List[Model]) deklariert, dass ein Endpunkt ein Array von Objekten zurückgibt. FastAPI validiert und serialisiert jedes Element der Liste.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

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

app = FastAPI()

@app.get("/items", response_model=list[Item])
def list_items():
    return [
        {"name": "Apple", "price": 0.5},
        {"name": "Banana", "price": 0.3},
    ]

# response: [{"name": "Apple", "price": 0.5}, {"name": "Banana", "price": 0.3}]

Unset/Defaults ausschließen

exclude_unset lässt Felder weg, die der Client nie gesendet hat (nur explizit gesetzte erscheinen). exclude_defaults lässt Felder weg, die ihrem Default entsprechen; exclude_none lässt None-Felder weg. Praktisch für schlanke Antworten.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

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

app = FastAPI()

@app.get("/items/{id}", response_model=Item, response_model_exclude_unset=True)
def read_item(id: int):
    return {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5}   (description, tax omitted)

# also: response_model_exclude_defaults=True
#       response_model_exclude_none=True

Antwort per Alias

Field(alias=...) lässt eingehendes JSON einen anderen Key-Namen als das Python-Attribut nutzen. response_model_by_alias=True gibt auch per Alias aus. populate_by_name=True erlaubt zusätzlich den originalen Attributnamen beim Input.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel, ConfigDict, Field

class Item(BaseModel):
    model_config = ConfigDict(populate_by_name=True)
    name: str = Field(alias="itemName")
    price: float

app = FastAPI()

@app.post("/items", response_model=Item, response_model_by_alias=True)
def create(item: Item):
    return item

# input:  {"itemName": "Apple", "price": 0.5}
# output: {"itemName": "Apple", "price": 0.5}

Plain-Dict-Antwort

Ein zurückgegebenes Dict/Liste serialisiert automatisch zu JSON. response_class ändert den Standard-Antworttyp (HTMLResponse, PlainTextResponse), oder direkt eine Response-Unterklasse für volle Kontrolle.

fastapi
from fastapi import FastAPI
from fastapi.responses import JSONResponse, PlainTextResponse

app = FastAPI()

@app.get("/dict")
def dict_resp():
    return {"a": 1, "b": 2}      # auto JSON

@app.get("/text", response_class=PlainTextResponse)
def text_resp():
    return "plain text response"

@app.get("/raw")
def raw_resp():
    return JSONResponse(content={"a": 1}, status_code=200)
06

Form & UploadFile

Formular-Daten

Form() deklariert einen Parameter aus application/x-www-form-urlencoded- oder multipart-Formulardaten. Form() lässt sich nicht mit einem JSON-Body (BaseModel) in derselben Operation mischen — ein Content-Typ wählen.

fastapi
from fastapi import FastAPI, Form

app = FastAPI()

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

# Content-Type: application/x-www-form-urlencoded
# body: username=bob&password=secret

UploadFile-Grundlagen

UploadFile ist eine Streaming-Datei-Repräsentation mit .filename, .content_type, .read(), .write(), .close(). Innerhalb von async def 'await file.read()' verwenden. Bei großen Dateien file.file (SpooledTemporaryFile) bevorzugen, um nicht alles in den Speicher zu laden.

fastapi
from fastapi import FastAPI, UploadFile, File

app = FastAPI()

@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
    contents = await file.read()
    return {
        "filename": file.filename,
        "size": len(contents),
        "content_type": file.content_type,
    }

Mehrere Dateien

list[UploadFile] deklarieren, um mehrere Dateien in einer Anfrage zu akzeptieren. Jede Datei wird mit demselben Feldnamen gesendet. Die Reihenfolge in der Liste entspricht der Sende-Reihenfolge.

fastapi
from fastapi import FastAPI, UploadFile

app = FastAPI()

@app.post("/uploads")
async def upload_many(files: list[UploadFile]):
    return [
        {"filename": f.filename, "size": len(await f.read())}
        for f in files
    ]

# curl: curl -F "[email protected]" -F "[email protected]" http://localhost:8000/uploads

File und Form zusammen

Form() und UploadFile (File()) lassen sich im selben Endpunkt kombinieren, weil beide multipart/form-data nutzen. Mit einem JSON-BaseModel-Body lassen sie sich weiterhin nicht kombinieren.

fastapi
from fastapi import FastAPI, UploadFile, File, Form

app = FastAPI()

@app.post("/items")
async def create_item(
    name: str = Form(),
    description: str = Form(),
    file: UploadFile = File(),
):
    return {
        "name": name,
        "description": description,
        "file": file.filename,
    }

Hochgeladene Datei speichern

Bei kleinen Dateien streamt shutil.copyfileobj das SpooledTemporaryFile effizient auf die Platte. Bei sehr großen Dateien in Chunks lesen (z. B. 1MB), um den Speicher niedrig zu halten. file.filename immer bereinigen, um Path-Traversal zu vermeiden.

fastapi
import shutil
from pathlib import Path
from fastapi import FastAPI, UploadFile

app = FastAPI()

@app.post("/save")
async def save_file(file: UploadFile):
    dest = Path("uploads") / file.filename
    dest.parent.mkdir(exist_ok=True)
    with dest.open("wb") as buf:
        shutil.copyfileobj(file.file, buf)
    return {"saved_to": str(dest)}

# async alternative for large files:
# async with dest.open("wb") as buf:
#     while chunk := await file.read(1024 * 1024):
#         buf.write(chunk)

Datei-Metadaten & Größe

file.content_type und Größe vor der Verarbeitung validieren. Nach read() steht der Cursor am Ende; 'await file.seek(0)' zurückspulen, falls erneut gelesen werden soll. Echte Typprüfung inspiziert Magic Bytes, nicht nur den Header.

fastapi
from fastapi import FastAPI, UploadFile, File

app = FastAPI()

@app.post("/validate")
async def validate(file: UploadFile = File(...)):
    # allowed types
    allowed = {"image/png", "image/jpeg"}
    if file.content_type not in allowed:
        return {"error": "unsupported type"}

    contents = await file.read()
    max_size = 5 * 1024 * 1024  # 5 MB
    if len(contents) > max_size:
        return {"error": "file too large"}

    await file.seek(0)  # rewind so later reads work
    return {"filename": file.filename, "size": len(contents)}
07

Header & Cookies

Header-Parameter

Header() deklariert einen Parameter aus den Request-Headern. FastAPI wandelt Unterstriche in Python-Namen zu Bindestrichen (x_token -> X-Token). convert_underscores=False schaltet das Verhalten ab.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

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

# Header names are case-insensitive; an underscore in the
# parameter (x_token) is converted to a hyphen (X-Token) automatically.
@app.get("/secure")
def secure(x_token: str = Header()):
    return {"x-token": x_token}

Cookie-Parameter

Cookie() liest einen Wert aus dem Cookie-Header der Anfrage. Wie Query-Params sind Cookies ohne Default erforderlich, und Validierung (min_length, max_length usw.) lässt sich anwenden.

fastapi
from fastapi import FastAPI, Cookie

app = FastAPI()

@app.get("/session")
def read_session(session_id: str | None = Cookie(default=None)):
    if session_id:
        return {"session_id": session_id}
    return {"message": "no session"}

# Reads the 'session_id' cookie from the Cookie header.

Cookie in der Antwort setzen

Ein Response injizieren und set_cookie() aufrufen, um Cookies auf der ausgehenden Antwort zu schreiben. httponly=True (blockiert JS-Zugriff), secure=True (nur HTTPS) und samesite='lax'/'strict' gegen CSRF. Der Antwort-Body wird normal zurückgegeben.

fastapi
from fastapi import FastAPI, Response

app = FastAPI()

@app.post("/login")
def login(response: Response):
    response.set_cookie(
        key="session_id",
        value="abc123",
        httponly=True,
        max_age=1800,
        secure=True,
        samesite="lax",
    )
    return {"message": "logged in"}

@app.post("/logout")
def logout(response: Response):
    response.delete_cookie("session_id")
    return {"message": "logged out"}

Eigene Response-Header

Header auf einem injizierten Response setzen, um sie zu jeder JSON-Antwort zu ergänzen, die FastAPI baut, oder headers= beim direkten Zurückgeben einer Response-Unterklasse übergeben. Eigene Header sind üblich für Rate-Limit-Infos und Prozess-Timing.

fastapi
from fastapi import FastAPI, Response
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/data")
def get_data(response: Response):
    response.headers["X-Process-Time"] = "0.05"
    response.headers["X-Custom-Header"] = "hello"
    return {"data": 1}

@app.get("/direct")
def direct():
    return JSONResponse(
        content={"data": 1},
        headers={"X-Source": "direct"},
    )

Standard-Header

Häufige Header wie Host, Accept, Authorization, If-None-Match sind über Header() erreichbar. Für Authorization die eingebauten Security-Utilities (HTTPBearer, OAuth2) bevorzugen — sie übernehmen Parsing und OpenAPI-Dokumentation.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/info")
def info(
    host: str | None = Header(default=None),
    accept: str | None = Header(default=None),
    authorization: str | None = Header(default=None),
    if_none_match: str | None = Header(default=None),
):
    return {"host": host, "accept": accept}

Doppelte Header-Werte

Ein Listentyp für einen Header-Parameter sammelt alle wiederholten Header-Werte in einer Liste. Praktisch für Header wie Set-Cookie (Response) oder eigene Header, die mehrfach auftreten können.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/multi")
def multi(x_token: list[str] | None = Header(default=None)):
    return {"x_token": x_token}

# Request with:
#   X-Token: a
#   X-Token: b
# -> {"x_token": ["a", "b"]}
08

Dependency Injection

Grundlegendes Depends

Depends() injiziert den Rückgabewert einer Funktion in deine path operation. Geteilte Logik (Pagination, Parsing, DB-Sessions) liegt an einem Ort und wird über Endpunkte wiederverwendet. Die Parameter der Dependency sind auch in OpenAPI dokumentiert.

fastapi
from fastapi import FastAPI, Depends

app = FastAPI()

def common_params(q: str | None = None, skip: int = 0, limit: int = 10):
    return {"q": q, "skip": skip, "limit": limit}

@app.get("/items")
def list_items(commons: dict = Depends(common_params)):
    return commons

@app.get("/users")
def list_users(commons: dict = Depends(common_params)):
    return commons

Klassen-Dependencies

Eine Klasse mit __init__ kann eine Dependency sein; FastAPI ruft sie wie eine Funktion auf. Depends(CommonQueryParams) oder die Kurzfassung Depends() verwenden, wenn der Parameter mit der Klasse annotiert ist. Die Instanz wird injiziert.

fastapi
from fastapi import FastAPI, Depends

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

app = FastAPI()

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

# shorthand: commons = Depends() infers the type

Verschachtelte Dependencies

Dependencies können selbst von anderen Dependencies abhängen und bilden so einen Graphen. FastAPI löst den ganzen Baum auf, cachet jedes Ergebnis pro Anfrage und propagiert Ausnahmen. Ideal für geschichtete Auth (token -> user -> permissions).

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def get_token(authorization: str = Header()):
    if not authorization.startswith("Bearer "):
        raise HTTPException(status_code=401, detail="invalid header")
    return authorization.removeprefix("Bearer ")

def get_current_user(token: str = Depends(get_token)):
    if token != "admin-token":
        raise HTTPException(status_code=403, detail="forbidden")
    return {"username": "admin"}

app = FastAPI()

@app.get("/me")
def me(user: dict = Depends(get_current_user)):
    return user

Yield-Dependencies (Cleanup)

Ein Dependency-Generator (yield) ist perfekt für Ressourcen mit Aufräumbedarf: DB-Sessions, Datei-Handles, Transaktionen. Code nach yield läuft als Finalizer, selbst wenn die Route eine Ausnahme wirft. Nur ein yield pro Dependency.

fastapi
from fastapi import FastAPI, Depends

def get_db():
    db = open_db_session()       # acquire resource
    try:
        yield db                 # injected into the route
    finally:
        db.close()               # always runs after the request

app = FastAPI()

@app.get("/items")
def list_items(db = Depends(get_db)):
    return db.query("SELECT * FROM items")

Globale Dependencies

dependencies=[...] an FastAPI() (oder einen APIRouter) übergeben, um sie auf jeder Route zu erzwingen, ohne den Rückgabewert zu injizieren. Nützlich für globale Auth, Rate Limiting oder Request-Logging.

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def verify_token(x_token: str = Header()):
    if x_token != "supersecret":
        raise HTTPException(status_code=400, detail="X-Token missing")

def verify_key(x_key: str = Header()):
    if x_key != "realkey":
        raise HTTPException(status_code=400, detail="X-Key missing")

# applied to every route in the app
app = FastAPI(dependencies=[Depends(verify_token), Depends(verify_key)])

@app.get("/items")
def list_items():
    return [{"item": "a"}]   # token & key already checked

Dependencies pro Route

dependencies=[Depends(...)] auf einem Decorator (oder APIRouter) verlangt eine Dependency für konkrete Routen, ohne ihren Rückgabewert zu nutzen. So bleiben die Routen-Signaturen sauber, während Checks durchgesetzt werden.

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def verify_token(x_token: str = Header()):
    if x_token != "secret":
        raise HTTPException(status_code=401, detail="bad token")

app = FastAPI()

@app.get("/public")
def public():
    return {"open": True}

@app.get("/private", dependencies=[Depends(verify_token)])
def private():
    return {"secret": "data"}
09

Sicherheit (HTTPBasic / OAuth2 / JWT)

HTTP Basic Auth

HTTPBasic parst den Authorization: Basic Header in username/password. secrets.compare_digest (nicht ==) verwenden, um Timing-Attacken zu verhindern. Immer 401 mit WWW-Authenticate: Basic zurückgeben, damit Browser nach Credentials fragen.

fastapi
import secrets
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials

security = HTTPBasic()
app = FastAPI()

def get_current_user(credentials: HTTPBasicCredentials = Depends(security)):
    correct_user = secrets.compare_digest(credentials.username, "admin")
    correct_pass = secrets.compare_digest(credentials.password, "secret")
    if not (correct_user and correct_pass):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid credentials",
            headers={"WWW-Authenticate": "Basic"},
        )
    return credentials.username

@app.get("/profile")
def profile(user: str = Depends(get_current_user)):
    return {"user": user}

OAuth2PasswordBearer

OAuth2PasswordBearer deklariert, dass Routen einen Bearer-Token erwarten; die Dependency extrahiert ihn aus dem Authorization-Header. tokenUrl sagt der Docs-UI, wohin Credentials gesendet werden. Der Token ist erstmal nur ein String, bis du ihn validierst.

fastapi
from fastapi import FastAPI, Depends
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
app = FastAPI()

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

# client POSTs username+password to /token, receives an access token,
# then sends it as: Authorization: Bearer <token>

JWT-Token erzeugen

python-jose (oder PyJWT) zum Signieren von Tokens. Der 'sub' (subject) Claim hält üblicherweise username oder user id, 'exp' setzt den Ablauf. SECRET_KEY lang, zufällig und aus der Umgebung laden — niemals committen.

fastapi
from datetime import datetime, timedelta, timezone
from jose import jwt

SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"

def create_access_token(data: dict, expires_minutes: int = 30) -> str:
    to_encode = data.copy()
    expire = datetime.now(timezone.utc) + timedelta(minutes=expires_minutes)
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

# token = create_access_token({"sub": "alice"})
# -> eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT-Token dekodieren

jwt.decode verifiziert Signatur und 'exp'-Claim automatisch und wirft bei Fehlschlag JWTError. Die Dependency auf eine 401 mit WWW-Authenticate: Bearer mappen, damit Clients wissen, dass sie einen gültigen Token liefern müssen.

fastapi
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import jwt, JWTError

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"

def get_current_user(token: str = Depends(oauth2_scheme)) -> str:
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str | None = payload.get("sub")
        if username is None:
            raise credentials_exception
        return username
    except JWTError:
        raise credentials_exception

credentials_exception = HTTPException(
    status_code=status.HTTP_401_UNAUTHORIZED,
    detail="Could not validate credentials",
    headers={"WWW-Authenticate": "Bearer"},
)

Passwort-Hashing

Passwörter niemals im Klartext speichern. passlib mit bcrypt (oder argon2) übernimmt Salting und Hashing. verify() vergleicht Klartext-Input mit einem gespeicherten Hash. pip install passlib[bcrypt] für das bcrypt-Backend.

fastapi
from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def hash_password(plain: str) -> str:
    return pwd_context.hash(plain)

def verify_password(plain: str, hashed: str) -> bool:
    return pwd_context.verify(plain, hashed)

# usage when issuing tokens:
def authenticate_user(username: str, password: str):
    user = fake_db.get(username)
    if not user or not verify_password(password, user.hashed_password):
        return False
    return user

OAuth2-Login-Fluss

OAuth2PasswordRequestForm liest username/password aus einem form-kodierten POST (der Standard-OAuth2-Passwort-Fluss). access_token und token_type: 'bearer' zurückgeben. Dieser Endpunkt ist das Ziel von tokenUrl in OAuth2PasswordBearer.

fastapi
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm

app = FastAPI()

@app.post("/token")
def login(form: OAuth2PasswordRequestForm = Depends()):
    user = authenticate_user(form.username, form.password)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
        )
    token = create_access_token({"sub": user.username})
    return {"access_token": token, "token_type": "bearer"}

# OAuth2PasswordRequestForm parses username+password from form data
# and powers the 'Authorize' button in the Swagger UI.
10

Middleware

Middleware ergänzen

@app.middleware('http') registriert eine Funktion, die jede Anfrage umwickelt. Sie muss await call_next(request) aufrufen, um die Antwort zu bekommen, kann sie dann inspizieren oder ändern. Middleware läuft für alle Routen.

fastapi
import time
from fastapi import FastAPI, Request

app = FastAPI()

@app.middleware("http")
async def add_process_time(request: Request, call_next):
    start = time.perf_counter()
    response = await call_next(request)
    duration = time.perf_counter() - start
    response.headers["X-Process-Time"] = f"{duration:.4f}"
    return response

Eigener Header-Middleware

Middleware ist der richtige Ort für Header, die auf jeder Antwort stehen sollen (Security-Header, Server-Banner, Tracing-IDs). Das Response-Objekt nach await call_next verändern.

fastapi
from fastapi import FastAPI, Request

app = FastAPI()

@app.middleware("http")
async def add_banner(request: Request, call_next):
    response = await call_next(request)
    response.headers["X-Powered-By"] = "FastAPI"
    response.headers["X-Frame-Options"] = "DENY"
    return response

# every response now carries these headers

BaseHTTPMiddleware

Für wiederverwendbare, konfigurierbare Middleware BaseHTTPMiddleware ableiten und mit app.add_middleware(MyMiddleware, **options) registrieren. So werden auch die eingebauten CORS-, GZip- und TrustedHost-Middlewares ergänzt.

fastapi
from starlette.middleware.base import BaseHTTPMiddleware
from fastapi import FastAPI, Request

class TimingMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        start = time.perf_counter()
        response = await call_next(request)
        response.headers["X-Duration"] = str(time.perf_counter() - start)
        return response

app = FastAPI()
app.add_middleware(TimingMiddleware)

# class-based middleware is reusable and configurable

HTTPS-Redirect

HTTPSRedirectMiddleware gibt für jede HTTP-Anfrage eine 308-Weiterleitung zur HTTPS-Version zurück. Hinter einem Load Balancer, der TLS terminiert, verwenden, damit Clients auf eine sichere Verbindung hochstufen.

fastapi
from fastapi import FastAPI
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware

app = FastAPI()
app.add_middleware(HTTPSRedirectMiddleware)

# all HTTP requests are redirected to HTTPS (308)

Trusted Host

TrustedHostMiddleware weist Anfragen ab, deren Host-Header nicht in der Allow-Liste steht, und verhindert Host-Header-Injection-Angriffe. Wildcards wie '*.example.com' werden unterstützt. 'localhost' für lokale Entwicklung immer aufnehmen.

fastapi
from fastapi import FastAPI
from fastapi.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI()
app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["example.com", "*.example.com", "localhost"],
)

# requests with a disallowed Host header get a 400 response

Middleware-Reihenfolge

Starlette führt Middleware für eingehende Anfragen in LIFO-Reihenfolge aus: die zuletzt ergänzte läuft zuerst. CORS früh ergänzen (damit Preflight funktioniert), GZip danach. Beim Debuggen daran denken, warum ein Header einer Middleware von einer anderen nicht gesehen wird.

fastapi
from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Middleware runs in REVERSE order of registration for requests,
# and in registration order for responses.
app.add_middleware(GZipMiddleware, minimum_size=1000)
app.add_middleware(CORSMiddleware, allow_origins=["*"])

# request flow:  CORS -> GZip -> route
# response flow: route -> GZip -> CORS
11

CORS

CORSMiddleware-Setup

CORSMiddleware behandelt den CORS-Preflight (OPTIONS) und ergänzt Access-Control-*-Header. allow_origins sollte die exakt erlaubten Ursprünge listen; in Produktion eine Liste konkreter URLs statt ['*'] verwenden.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://example.com", "https://www.example.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/api/data")
def data():
    return {"data": 1}

Alle Ursprünge erlauben (nur Dev)

allow_origins=['*'] erlaubt jeden Ursprung, kann aber nicht mit allow_credentials=True kombiniert werden (Browser lehnen es ab). Nur für völlig öffentliche APIs in der Entwicklung; in Produktion die realen Ursprünge aufzählen.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
    # allow_credentials=True CANNOT be combined with allow_origins=["*"]
)

Credentials erlauben

allow_credentials=True lässt den Browser Cookies und Authorization-Header cross-origin senden. Es verlangt konkrete Ursprünge (niemals '*'). Der Browser setzt Access-Control-Allow-Credentials: true auf Antworten.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_credentials=True,    # send cookies / Authorization
    allow_methods=["GET", "POST"],
    allow_headers=["Authorization", "Content-Type"],
)

# needed when the frontend sends cookies or credentials with requests

Erlaubte Methoden & Header

allow_methods/allow_headers beschränken, was der Browser senden darf. expose_headers listet Response-Header, die das Frontend-JavaScript lesen darf (Browser verbergen sonst eigene Header). Preflight-Antworten werden vom Browser gecacht.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
    allow_headers=["Authorization", "Content-Type", "X-Request-ID"],
    expose_headers=["X-Total-Count", "X-Process-Time"],
)

# expose_headers lets the frontend JS read these response headers

Preflight-Anfragen

Für 'non-simple'-Anfragen (eigene Header, PUT/DELETE, JSON-Content-Type) sendet der Browser einen OPTIONS-Preflight. CORSMiddleware fängt OPTIONS ab und antwortet mit den erlaubten Methoden/Headern. max_age steuert, wie lange der Browser die Antwort cached.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_methods=["*"],
    allow_headers=["*"],
    max_age=600,   # browser caches preflight result for 600s
)

# Browser sends OPTIONS preflight for non-simple requests;
# CORSMiddleware answers automatically with the right headers.

Dynamische Origin-Validierung

Für dynamische Allow-Listen allow_origin_regex (matcht gegen den Origin der Anfrage) statt einer statischen Liste verwenden. Praktisch, wenn gültige Ursprünge einem Muster folgen (z. B. jede Subdomain von example.com).

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

VALID_DOMAINS = {"example.com", "staging.example.com"}

def origin_check(origin: str) -> str | None:
    if origin and origin.replace("https://", "").replace("http://", "") in VALID_DOMAINS:
        return origin
    return None

app.add_middleware(
    CORSMiddleware,
    allow_origin_regex=r"https://.*\.example\.com",
    allow_methods=["*"],
    allow_headers=["*"],
)
12

Ausnahmebehandlung

HTTPException werfen

raise HTTPException irgendwo in einer Route oder Dependency, um kurzzuschließen und eine Fehlerantwort zurückzugeben. detail kann ein String, Dict oder Liste sein — es wird zum JSON-'detail'-Feld. headers ergänzt optional Response-Header.

fastapi
from fastapi import FastAPI, HTTPException, status

app = FastAPI()

items = {1: "Apple", 2: "Banana"}

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id not in items:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
            headers={"X-Error": "missing"},
        )
    return {"item": items[item_id]}

Eigene Ausnahme

Einen Handler mit @app.exception_handler(MyException) registrieren, um jede eigene Ausnahme in eine HTTP-Antwort umzuwandeln. Der Handler erhält die Anfrage und die Ausnahme. So wird Fehlerformatierung für Domänen-Fehler zentralisiert.

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

class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name

app = FastAPI()

@app.exception_handler(UnicornException)
async def unicorn_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops, {exc.name} did it again"},
    )

@app.get("/unicorns/{name}")
def read_unicorn(name: str):
    if name == "yolo":
        raise UnicornException(name=name)
    return {"name": name}

Validierungs-Fehler überschreiben

RequestValidationError wird geworfen, wenn Input die Pydantic-Validierung nicht besteht. Seinen Handler mit @app.exception_handler(RequestValidationError) überschreiben, um die 422-Antwortform anzupassen, z. B. an einen firmenweiten Error-Envelope.

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

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content={
            "success": False,
            "errors": exc.errors(),
            "body": exc.body,
        },
    )

HTTPException-Handler überschreiben

Den Default-HTTPException-Handler überschreiben, um eine konsistente Fehler-JSON-Form über alle geworfenen HTTPExceptions durchzusetzen. Beim Neu-Binden die Klasse als fastapi.exceptions.HTTPException importieren (dieselbe, die raise nutzt).

fastapi
from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse
from fastapi.exceptions import HTTPException as FastAPIHTTPException

app = FastAPI()

@app.exception_handler(FastAPIHTTPException)
async def custom_http_handler(request, exc: FastAPIHTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "success": False,
            "status": exc.status_code,
            "message": exc.detail,
        },
        headers=exc.headers,
    )

Häufige Statuscodes

Das status-Modul liefert benannte Konstanten für alle HTTP-Statuscodes und vermeidet magische Zahlen. 200 (Default GET), 201 (created), 204 (no content), 422 (validation) sind in FastAPI-Apps die häufigsten.

fastapi
from fastapi import FastAPI, status

app = FastAPI()

@app.get("/ok", status_code=status.HTTP_200_OK)
def ok(): return {"ok": True}

@app.post("/create", status_code=status.HTTP_201_CREATED)
def create(): return {"id": 1}

@app.get("/no-content", status_code=status.HTTP_204_NO_CONTENT)
def no_content(): return None

@app.get("/not-found")
def missing():
    # raise HTTPException(status.HTTP_404_NOT_FOUND, "nope")
    ...

# Other common: 400 BAD_REQUEST, 401 UNAUTHORIZED,
# 403 FORBIDDEN, 409 CONFLICT, 422 UNPROCESSABLE_ENTITY, 500 INTERNAL_SERVER_ERROR

Generischer Exception-Handler

Ein Handler für die Basis-Exception fängt alles Unbehandelte und verhindert, dass Stack-Traces zu Clients durchsickern. Den vollen Traceback immer serverseitig loggen; dem Client eine generische 500 zurückgeben.

fastapi
import logging
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

logger = logging.getLogger("uvicorn.error")
app = FastAPI()

@app.exception_handler(Exception)
async def unhandled(request: Request, exc: Exception):
    logger.exception("Unhandled error on %s", request.url.path)
    return JSONResponse(
        status_code=500,
        content={"detail": "Internal Server Error"},
    )

@app.get("/boom")
def boom():
    raise RuntimeError("something exploded")
13

Background Tasks

Grundlegendes BackgroundTasks

BackgroundTasks führt Funktionen aus, nachdem die Antwort gesendet wurde — perfekt für Fire-and-Forget-Arbeit wie Logging, E-Mails oder Cache-Invalidierung. add_task plant eine Funktion (und Argumente), ohne die Antwort zu blockieren.

fastapi
from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def write_log(message: str):
    with open("log.txt", "a") as f:
        f.write(message + "\n")

@app.post("/send")
def send_notification(background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, "notification sent")
    return {"message": "notification queued"}

Mehrere Tasks

So viele Tasks ergänzen wie gewünscht; sie laufen sequenziell in Ergänzungs-Reihenfolge, nachdem die Antwort zurückgegeben wurde. Weil sie im selben Prozess laufen, sie kurz und nicht-blockierend halten oder auf eine echte Queue umsteigen (Celery, RQ, Dramatiq).

fastapi
from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def send_email(to: str, subject: str): ...
def update_cache(key: str): ...
def notify_slack(msg: str): ...

@app.post("/signup")
def signup(background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email, "[email protected]", "Welcome")
    background_tasks.add_task(update_cache, "user_count")
    background_tasks.add_task(notify_slack, "new signup")
    return {"status": "ok"}

Task mit Dependencies

BackgroundTasks wird wie jede andere Dependency injiziert. Die Task-Funktion kann Werte (wie eine DB-Session) erhalten, die zur Anfragezeit erfasst wurden. Hinweis: yield/close-Ressourcen aus Dependencies schließen erst nach Task-Ende, da Tasks im Lebenszyklus-Scopes der Anfrage laufen.

fastapi
from fastapi import FastAPI, BackgroundTasks, Depends

app = FastAPI()

def get_db_session():
    db = "session"
    yield db

def write_log(db, message: str):
    print(db, message)

@app.get("/items")
def list_items(background_tasks: BackgroundTasks, db = Depends(get_db_session)):
    background_tasks.add_task(write_log, db, "list called")
    return {"items": []}

Async-Task-Funktion

Background-Task-Funktionen können sync (läuft im Threadpool) oder async (awaited auf der Event-Loop) sein. Async-Tasks für I/O-lastige Arbeit, die selbst async-Bibliotheken nutzt, sync-Tasks für CPU-/blockierende Arbeit.

fastapi
from fastapi import FastAPI, BackgroundTasks
import httpx

app = FastAPI()

async def fetch_url(url: str):
    async with httpx.AsyncClient() as client:
        r = await client.get(url)
        return r.status_code

@app.post("/webhook")
def webhook(url: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(fetch_url, url)
    return {"queued": url}

Background vs. Celery

BackgroundTasks für leichtgewichtige, unkritische Arbeit, die bei Neustart verloren gehen darf. Für Jobs, die Crashes überleben, Retries oder Maschinen-übergreifende Skalierung brauchen, eine echte Task-Queue (Celery, RQ, Dramatiq, Arq) mit einem Broker wie Redis oder RabbitMQ.

fastapi
# BackgroundTasks: in-process, no broker, lost if process crashes
@app.post("/quick")
def quick(tasks: BackgroundTasks):
    tasks.add_task(small_job)
    return {"ok": True}

# Celery/RQ/Dramatiq: separate workers, persistent, retryable
# from celery import Celery
# @celery.task
# def big_job(payload): ...
#
# @app.post("/heavy")
# def heavy(payload: dict):
#     big_job.delay(payload)
#     return {"queued": True}

E-Mail-Versand-Beispiel

E-Mail-Versand ist der klassische BackgroundTasks-Fall: langsam, und der Nutzer soll nicht warten. Die Antwort kommt sofort, während die E-Mail danach rausgeht. Bei hohem Volumen eine Queue und ein E-Mail-Service-SDK mit Retries bevorzugen.

fastapi
from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel, EmailStr

class Message(BaseModel):
    to: EmailStr
    subject: str
    body: str

app = FastAPI()

def send_email(to: str, subject: str, body: str):
    # smtplib or your provider's SDK
    import smtplib
    with smtplib.SMTP("localhost") as s:
        s.sendmail("[email protected]", to, f"Subject: {subject}\n\n{body}")

@app.post("/contact")
def contact(msg: Message, tasks: BackgroundTasks):
    tasks.add_task(send_email, msg.to, msg.subject, msg.body)
    return {"status": "queued", "to": msg.to}
14

WebSocket

WebSocket-Grundlagen

@app.websocket() definiert einen WebSocket-Endpunkt. Vor Senden/Empfangen muss accept() aufgerufen werden. Die Funktion looped typischerweise lesend; receive_text/receive_bytes/receive_json awaiten alle Daten vom Client.

fastapi
from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
    await ws.accept()
    while True:
        data = await ws.receive_text()
        await ws.send_text(f"echo: {data}")

# client (browser):
# const ws = new WebSocket("ws://localhost:8000/ws");
# ws.onmessage = (e) => console.log(e.data);

JSON senden

send_json() und receive_json() übernehmen die Serialisierung und tauschen JSON-Objekte über den Socket aus. Für Binärdaten send_bytes/receive_bytes. Jedes send/receive ist ein separater Frame auf dem WebSocket.

fastapi
import json
from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    await ws.accept()
    while True:
        msg = await ws.receive_json()
        await ws.send_json({"reply": msg.get("text", "").upper()})

# send_text / send_bytes / send_json helpers are available

WebSocket schließen

WebSocketDisconnect wird geworfen, wenn der Client die Verbindung schließt — fangen, um aufzuräumen. ws.close(code=1000) für einen normalen Abschluss; übliche Codes: 1000 (normal), 1008 (policy violation), 1011 (server error).

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

app = FastAPI()

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    await ws.accept()
    try:
        while True:
            data = await ws.receive_text()
            if data == "quit":
                await ws.close(code=1000)
                break
            await ws.send_text(data)
    except WebSocketDisconnect:
        print("client disconnected")

Connection-Manager

Ein ConnectionManager verfolgt aktive Sockets, damit man an alle verbundenen Clients broadcasten kann (z. B. ein Chatraum). Den Socket bei Disconnect immer entfernen, um nicht an geschlossene Verbindungen zu senden und Speicher begrenzt zu halten.

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

class ConnectionManager:
    def __init__(self):
        self.active: list[WebSocket] = []

    async def connect(self, ws: WebSocket):
        await ws.accept()
        self.active.append(ws)

    def disconnect(self, ws: WebSocket):
        self.active.remove(ws)

    async def broadcast(self, message: str):
        for ws in self.active:
            await ws.send_text(message)

manager = ConnectionManager()
app = FastAPI()

@app.websocket("/chat")
async def chat(ws: WebSocket):
    await manager.connect(ws)
    try:
        while True:
            msg = await ws.receive_text()
            await manager.broadcast(msg)
    except WebSocketDisconnect:
        manager.disconnect(ws)

WebSocket-Auth per Query-Param

Browser können bei WebSocket-Verbindungen keine eigenen Header setzen, daher laufen Auth-Tokens üblicherweise als Query-Parameter (oder Cookies). Vor accept() validieren und bei Unautorisierung mit Code 1008 (policy violation) schließen.

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect, HTTPException

app = FastAPI()

async def authenticate(token: str) -> str:
    if token != "secret":
        raise HTTPException(status_code=401)
    return "alice"

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    token = ws.query_params.get("token")
    if not token:
        await ws.close(code=1008)
        return
    user = await authenticate(token)
    await ws.accept()
    try:
        while True:
            data = await ws.receive_text()
            await ws.send_text(f"{user}: {data}")
    except WebSocketDisconnect:
        pass

WebSocket mit Dependencies

Dependencies funktionieren in WebSocket-Endpunkten wie in HTTP-Routen, aber nur solche, die aus dem initialen Handshake lesen (Header, Query-Params, Cookies) machen Sinn — es gibt keinen Body. Üblich über Depends() injizieren.

fastapi
from fastapi import FastAPI, WebSocket, Depends, Header

app = FastAPI()

def token_validator(token: str = Header(default="")):
    # for WS, headers come from the initial HTTP handshake
    return token == "valid"

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket, valid: bool = Depends(token_validator)):
    if not valid:
        await ws.close(code=1008)
        return
    await ws.accept()
    while True:
        msg = await ws.receive_text()
        await ws.send_text(msg)
15

Datenbank (SQLAlchemy)

SQLAlchemy-Setup

create_engine richtet den DB-Verbindungspool ein; SessionLocal ist eine Factory für Sessions; Base ist das deklarative Basis für Models. Für SQLite mit FastAPI check_same_thread=False setzen, weil Anfragen in verschiedenen Threads laufen können.

fastapi
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

SQLALCHEMY_DATABASE_URL = "sqlite:///./app.db"
# postgresql: "postgresql://user:pass@localhost:5432/dbname"

engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    connect_args={"check_same_thread": False},  # sqlite only
)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
Base = declarative_base()

Session-Dependency

Eine yield-Dependency ist der kanonische Weg, eine DB-Session bereitzustellen: jede Anfrage bekommt eine frische Session, die im finally-Block geschlossen wird. Das garantiert Aufräumen, selbst wenn die Route eine Ausnahme wirft.

fastapi
from fastapi import Depends
from sqlalchemy.orm import Session

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

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

# each request gets its own session, closed automatically afterward

Model-Definition

Tabellen als SQLAlchemy-ORM-Models definieren, die Base ableiten. In Produktion Alembic für Schema-Migrationen statt create_all(). Spalten können indexiert, nullable sein und Defaults auf DB- oder Python-Ebene bekommen.

fastapi
from sqlalchemy import Column, Integer, String, Boolean
from sqlalchemy.orm import declarative_base

Base = declarative_base()

class Item(Base):
    __tablename__ = "items"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True, nullable=False)
    price = Column(Integer, default=0)
    in_stock = Column(Boolean, default=True)

# create tables (for dev; use Alembic migrations in prod)
Base.metadata.create_all(bind=engine)

Datensatz erzeugen

add() stützt eine neue Zeile, commit() schreibt sie in die DB, und refresh() lädt die Instanz mit servergenerierten Werten neu (wie die auto-increment id). Mehrere Schreibvorgänge in eine Transaktion wickeln und einmal am Ende committen.

fastapi
from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session

app = FastAPI()

@app.post("/items", status_code=201)
def create_item(payload: ItemCreate, db: Session = Depends(get_db)):
    item = Item(name=payload.name, price=payload.price)
    db.add(item)
    db.commit()
    db.refresh(item)        # load generated id
    return item

Datensätze abfragen

db.query(Model) startet eine Abfrage; .filter() wendet WHERE-Bedingungen an, .offset()/.limit() paginieren, .first() gibt eine Zeile oder None zurück, .all() eine Liste. .filter_by(name=x) für einfache Gleichheits-Bedingungen.

fastapi
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session

app = FastAPI()

@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
    return db.query(Item).offset(skip).limit(limit).all()

@app.get("/items/{item_id}")
def get_item(item_id: int, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    return item

Update & Delete

Für Teilupdates über model_dump(exclude_unset=True) iterieren, sodass nur gelieferte Felder ändern. delete() stützt die Entfernung; commit() finalisiert. Bei DELETE-Erfolg 204 No Content zurückgeben.

fastapi
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session

app = FastAPI()

@app.put("/items/{item_id}")
def update_item(item_id: int, payload: ItemUpdate, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    for k, v in payload.model_dump(exclude_unset=True).items():
        setattr(item, k, v)
    db.commit()
    db.refresh(item)
    return item

@app.delete("/items/{item_id}", status_code=204)
def delete_item(item_id: int, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if item:
        db.delete(item)
        db.commit()
16

Datenbank (Tortoise ORM)

Tortoise-Setup

Tortoise ORM ist async-nativ und passt gut zu FastAPI. Beim Startup mit db_url und dem/den Modul(n) mit deinen Models initialisieren. generate_schemas() ist für Dev okay; in Produktion Aerich für Migrationen. In neuem Code den lifespan-Handler statt on_event verwenden.

fastapi
from fastapi import FastAPI
from tortoise import Tortoise

app = FastAPI()

async def init():
    await Tortoise.init(
        db_url="sqlite://db.sqlite3",
        modules={"models": ["app.models"]},
    )
    await Tortoise.generate_schemas()

@app.on_event("startup")
async def startup():
    await init()

@app.on_event("shutdown")
async def shutdown():
    await Tortoise.close_connections()

Model-Definition

Tortoise-Models erben von Model und deklarieren Felder über tortoise.fields. Feldtypen mappen auf DB-Spaltentypen. Tabellennamen in der inneren Meta-Klasse setzen. Beziehungen nutzen ForeignKeyField, ManyToManyField usw.

fastapi
from tortoise import fields
from tortoise.models import Model

class Item(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=100)
    price = fields.FloatField(default=0.0)
    created_at = fields.DatetimeField(auto_now_add=True)

    class Meta:
        table = "items"

    def __str__(self):
        return self.name

Datensatz erzeugen

Item.create() ist eine Coroutine, die einfügt und die neue Zeile zurückgibt. Für eine Pydantic-Antwort ein BaseModel mit from_tortoise_orm() bauen (über tortoise.contrib.pydantic), damit Tortoise async geladene Relationen korrekt serialisiert.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel
from .models import Item

app = FastAPI()

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

@app.post("/items", response_model=ItemOut, status_code=201)
async def create_item(payload: ItemIn):
    item = await Item.create(name=payload.name, price=payload.price)
    return await ItemOut.from_tortoise_orm(item)

Async-Abfrage

Tortoise-Abfragen werden awaited: .all() gibt ein queryset zurück, .filter() ergänzt Bedingungen, .get_or_none() holt eine Zeile oder None, .first() den ersten Treffer. .get() vermeiden, außer man erwartet genau eine Zeile (wirft, wenn nicht gefunden).

fastapi
from fastapi import FastAPI, HTTPException
from .models import Item

app = FastAPI()

@app.get("/items")
async def list_items(skip: int = 0, limit: int = 10):
    return await Item.all().offset(skip).limit(limit)

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    item = await Item.get_or_none(id=item_id)
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    return item

Update & Delete

Model-Attribute ändern, dann await save() zum Aktualisieren einer Zeile, oder await Item.filter(id=...).update(name=x) für Bulk-Updates. await item.delete() entfernt die Zeile. Jede Methode ist eine Coroutine und muss awaited werden.

fastapi
from fastapi import FastAPI, HTTPException
from .models import Item

app = FastAPI()

@app.put("/items/{item_id}")
async def update_item(item_id: int, name: str):
    item = await Item.get_or_none(id=item_id)
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    item.name = name
    await item.save()
    return item

@app.delete("/items/{item_id}", status_code=204)
async def delete_item(item_id: int):
    item = await Item.get_or_none(id=item_id)
    if item:
        await item.delete()

Tortoise-Pydantic-Schemas

tortoise.contrib.pydantic generiert Pydantic-Models direkt aus Tortoise-Models, sodass man nicht zwei Schemas pflegt. pydantic_model_creator für ein einzelnes Objekt, pydantic_queryset_creator für eine Listen-Antwort.

fastapi
from tortoise.contrib.pydantic import pydantic_model_creator, pydantic_queryset_creator
from .models import Item

ItemOut = pydantic_model_creator(Item, name="ItemOut")
ItemList = pydantic_queryset_creator(Item)

@app.get("/items", response_model=ItemList)
async def list_items():
    return await Item.all()

# auto-generates a Pydantic model from the Tortoise model,
# including types and docstrings.
17

Testen (TestClient)

TestClient-Grundlagen

TestClient umwickelt deine App und erlaubt Anfragen im Prozess (kein echter Socket). Basiert auf httpx und funktioniert out of the box mit pytest. Denselben App-Instance importieren, den du in Produktion betreibst.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

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

# TestClient is based on httpx; no network is involved —
# it calls the ASGI app directly in-process.

GET & POST testen

json= für JSON-Bodies, params= für Query-Params, headers= für Header und files= für multipart-Uploads übergeben. Validierungs-Fehler geben 422 — auf status_code und die Struktur des Fehler-'detail' assertionen.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_create_item():
    response = client.post(
        "/items",
        json={"name": "Apple", "price": 0.5},
    )
    assert response.status_code == 201
    assert response.json()["name"] == "Apple"

def test_validation_error():
    response = client.post("/items", json={"name": "Apple"})  # missing price
    assert response.status_code == 422

Pytest-Fixture

Eine pytest-Fixture, die einen TestClient zurückgibt, hält Tests DRY und gibt jedem Test einen frischen Client. Für DB-basierte Tests eine Fixture ergänzen, die Tabellen erzeugt/droppt oder pro Test einen Transaktions-Rollback nutzt, um sie zu isolieren.

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

@pytest.fixture
def client():
    return TestClient(app)

def test_read(client):
    r = client.get("/items")
    assert r.status_code == 200

def test_create(client):
    r = client.post("/items", json={"name": "X"})
    assert r.status_code == 201

# run: pytest -v

Dependencies überschreiben

app.dependency_overrides tauscht eine Dependency (etwa die echte DB-Session oder Auth) während der Tests gegen ein Mock/Fake, ohne die Routen zu ändern. Der kanonische Weg, Endpunkte isoliert von externen Diensten zu testen. Nach den Tests leeren.

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

def get_test_db():
    # return a test session or mock
    yield FakeSession()

app.dependency_overrides[get_db] = get_test_db

client = TestClient(app)

def test_items():
    r = client.get("/items")
    assert r.status_code == 200

# restore afterwards:
app.dependency_overrides.clear()

Authentifizierung testen

OAuth2PasswordRequestForm erwartet form-kodierte Daten (data=, nicht json=). Den zurückgegebenen Token im Authorization: Bearer-Header für nachfolgende geschützte Anfragen verwenden. Um Auth ganz zu umgehen, stattdessen die get_current_user-Dependency überschreiben.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def get_token():
    r = client.post(
        "/token",
        data={"username": "admin", "password": "secret"},
    )
    return r.json()["access_token"]

def test_protected():
    token = get_token()
    r = client.get(
        "/me",
        headers={"Authorization": f"Bearer {token}"},
    )
    assert r.status_code == 200
    assert r.json()["username"] == "admin"

WebSocket testen

TestClient.websocket_connect() öffnet einen WebSocket innerhalb eines Context-Managers. send_text/receive_text (und die json/bytes-Varianten) zum Austausch von Nachrichten. Empfangen auf einer geschlossenen Verbindung wirft WebSocketDisconnect.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_websocket():
    with client.websocket_connect("/ws") as ws:
        ws.send_text("hello")
        data = ws.receive_text()
        assert data == "echo: hello"

def test_websocket_close():
    with client.websocket_connect("/ws") as ws:
        ws.send_text("quit")
        # the server closes the connection
18

OpenAPI-Docs

Swagger UI

FastAPI generiert automatisch eine interaktive Swagger UI unter /docs aus deinen Routen, Typen und Docstrings. title/description/version an der App setzen und pro Route einen Docstring oder summary/description ergänzen, um die UI anzureichern.

fastapi
from fastapi import FastAPI

app = FastAPI(
    title="My API",
    description="Sample API with auto docs",
    version="1.0.0",
)

@app.get("/items", summary="List items", description="Returns all items")
def list_items():
    """Get every item in the catalog."""
    return [{"id": 1}]

# interactive docs at: http://localhost:8000/docs

ReDoc

ReDoc unter /redoc ist eine read-only, dokumentationsfokussierte Alternative zu Swagger. Das rohe OpenAPI-Schema liegt unter /openapi.json und lässt sich anderen Tools füttern. Docs abschalten mit docs_url=None, redoc_url=None, openapi_url=None (z. B. in Produktion).

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"hello": "world"}

# ReDoc (alternative docs UI) at: http://localhost:8000/redoc
# raw OpenAPI JSON at: http://localhost:8000/openapi.json

# disable docs entirely:
# app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)

Tags & Gruppierung

Tags gruppieren Routen in der Docs-UI. Tag-Metadaten (name, description, externalDocs) vorab in openapi_tags deklarieren, damit die Gruppe schon erscheint, bevor eine Route sie nutzt. deprecated=True markiert einen Endpunkt in den Docs als veraltet.

fastapi
from fastapi import FastAPI

app = FastAPI(openapi_tags=[
    {"name": "users", "description": "User management"},
    {"name": "items", "description": "Item operations"},
])

@app.get("/users", tags=["users"])
def list_users(): ...

@app.post("/items", tags=["items"])
def create_item(): ...

@app.get("/items/{id}", tags=["items"], deprecated=True)
def get_item(id: int): ...

Routen-Metadaten

Decoratoren akzeptieren Metadaten, die in OpenAPI fließen: summary (kurzer Titel), description (langer Text), response_description, tags, deprecated und status_code. Ein Docstring wird als description genutzt, wenn nicht explizit einer übergeben wird.

fastapi
from fastapi import FastAPI, status
from pydantic import BaseModel

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

app = FastAPI()

@app.post(
    "/items",
    response_model=Item,
    status_code=status.HTTP_201_CREATED,
    summary="Create an item",
    description="Creates a new item and returns it.",
    tags=["items"],
    response_description="The created item",
)
def create_item(item: Item):
    """Create endpoint docstring — also shown in docs."""
    return item

Feld-Beispiele

Field(examples=[...]) und Body(examples=[...]) ergänzen Beispiel-Payloads zur Swagger-UI-'Try it out' und der Beispiele-Dropdown. Body-Beispiele können mehrere Fälle mit summaries enthalten, um gültige und ungültige Inputs zu zeigen.

fastapi
from pydantic import BaseModel, Field
from fastapi import FastAPI, Body

class Item(BaseModel):
    name: str = Field(examples=["Apple"])
    price: float = Field(examples=[0.5], gt=0)

app = FastAPI()

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

@app.post("/manual")
def manual(
    item: Item = Body(
        examples=[
            {"summary": "valid", "value": {"name": "Apple", "price": 0.5}},
            {"summary": "invalid", "value": {"name": "Apple", "price": -1}},
        ],
    ),
):
    return item

Eigenes OpenAPI-Schema

app.openapi überschreiben, um das generierte Schema anzupassen — ein Logo, extra Metadaten oder Operationen entfernen/transformieren. Das Ergebnis in app.openapi_schema cachen, damit es nur einmal erzeugt wird. Das Schema ist das, was /openapi.json ausliefert.

fastapi
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    schema = get_openapi(
        title="Custom API",
        version="2.0.0",
        routes=app.routes,
    )
    schema["info"]["x-logo"] = {"url": "https://example.com/logo.png"}
    app.openapi_schema = schema
    return schema

app.openapi = custom_openapi
19

Deployment (Uvicorn / Gunicorn)

Uvicorn in Produktion

In Produktion Uvicorn hinter einem Reverse-Proxy (Nginx, Caddy, Cloud-Load-Balancer) betreiben. --proxy-headers verwenden, damit die App die echte Client-IP/Host aus X-Forwarded-For/X-Forwarded-Proto sieht. --reload in Produktion vermeiden.

fastapi
# Run directly with uvicorn (single worker)
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1

# Recommended: behind a reverse proxy (nginx) on port 8000
# Use --proxy-headers so X-Forwarded-* is trusted
uvicorn main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips='*'

Gunicorn mit Uvicorn-Workern

Gunicorn verwaltet mehrere Uvicorn-Worker-Prozesse und bringt graceful reloads, Neustarts bei Crash und Pre-Fork-Skalierung. Die UvicornWorker-Klasse verwenden. workers auf (2 * CPU-Kerne + 1) als Startpunkt setzen, dann benchmarken.

fastapi
# install the uvicorn worker class
pip install "uvicorn[standard]" gunicorn

# run 4 worker processes managed by gunicorn
gunicorn main:app \
    -w 4 \
    -k uvicorn.workers.UvicornWorker \
    -b 0.0.0.0:8000 \
    --timeout 120

# -w workers (commonly 2*CPU+1), -k worker class

Docker-Deployment

Ein schlankes Python-Basis-Image hält das Image klein. Abhängigkeiten vor dem Kopieren des Codes installieren, um Docker's Layer-Cache zu nutzen. Im Container mit gunicorn+uvicorn workern laufen lassen und Port 8000 zum Host oder Orchestrator exponieren.

fastapi
# Dockerfile
FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["gunicorn", "main:app", "-w", "4", \
     "-k", "uvicorn.workers.UvicornWorker", \
     "-b", "0.0.0.0:8000"]

# build & run:
# docker build -t myapi .
# docker run -p 8000:8000 myapi

Umgebungs-Konfiguration

pydantic-settings (ehemals pydantic.BaseSettings) lädt Konfiguration aus Umgebungsvariablen und .env-Dateien mit Typvalidierung. So läuft dasselbe Image in verschiedenen Umgebungen (dev/staging/prod), allein durch geänderte Env-Variablen.

fastapi
import os
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str = "sqlite:///./app.db"
    secret_key: str = "change-me"
    debug: bool = False
    allowed_origins: list[str] = ["http://localhost:3000"]

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"

settings = Settings()

# .env file:
# DATABASE_URL=postgresql://user:pass@db:5432/app
# SECRET_KEY=long-random-string
# DEBUG=false

Nginx-Reverse-Proxy

Nginx terminiert HTTP(S) und leitet an Uvicorn auf localhost:8000 weiter. Die X-Forwarded-*-Header setzen (und --proxy-headers auf Uvicorn), damit die App die echte Client-IP und das Schema sieht. Die Upgrade/Connection-Zeilen ermöglichen WebSocket-Support.

fastapi
# /etc/nginx/conf.d/api.conf
server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;

        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Skalierung & Nebenläufigkeit

Zwei Wege skalieren: mehr Uvicorn-Worker-Prozesse pro Maschine (CPU-gebunden) und mehr Maschinen hinter einem Load Balancer (horizontal). Bei Async-Apps übernimmt die Event-Loop viele gleichzeitige I/O-Anfragen pro Worker. Einen /health-Endpunkt ergänzen, damit Orchestratoren (k8s, ECS) Liveness prüfen können.

fastapi
# Workers = process count (vertical scaling); pick ~2*CPU
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

# Inside async app: concurrency is cooperative via the event loop.
# CPU-bound work blocks it — offload to a threadpool or task queue.

# Horizontal scaling: run several containers behind a load balancer.
# Use a shared store (Redis) for session state and rate limits.

# Health check endpoint for the balancer:
@app.get("/health")
def health():
    return {"status": "ok"}
20

Fortgeschrittene Themen

Lifespan-Events

Der lifespan-Kontextmanager ersetzt die veralteten on_event('startup'/'shutdown')-Handler. Code vor yield läuft beim Start; Code nach yield beim Herunterfahren, selbst wenn der Start scheitert. Damit DB-Verbindungen, ML-Models und Caches initialisieren.

fastapi
from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    # runs at startup
    print("starting up")
    app.state.cache = {}
    yield
    # runs at shutdown
    print("shutting down")
    await app.state.cache.clear()

app = FastAPI(lifespan=lifespan)

# the old @app.on_event("startup") / "shutdown" are deprecated
# in favor of the lifespan handler above.

Sub-Applications (Mount)

app.mount() hängt eine Sub-Application unter ein Pfad-Präfix — nützlich für versionierte APIs oder das Kombinieren mehrerer Apps. Jede Sub-App hat eigene Routen und ein eigenes OpenAPI-Schema; die Docs des Parents enthalten die Routen des Kindes standardmäßig nicht.

fastapi
from fastapi import FastAPI

app = FastAPI()

api_v1 = FastAPI()
api_v2 = FastAPI()

@api_v1.get("/items")
def v1_items():
    return {"version": 1}

@api_v2.get("/items")
def v2_items():
    return {"version": 2}

app.mount("/v1", api_v1)
app.mount("/v2", api_v2)

# GET /v1/items -> {"version": 1}
# GET /v2/items -> {"version": 2}

APIRouter

APIRouter gruppiert zugehörige Routen zu einem Modul mit geteiltem prefix, tags, dependencies und responses. Einbinden über app.include_router(router) (optional mit eigenem prefix oder tags). Das Standardmuster für strukturierte, nicht-triviale Apps.

fastapi
from fastapi import APIRouter, Depends

router = APIRouter(
    prefix="/items",
    tags=["items"],
    dependencies=[Depends(verify_token)],
    responses={404: {"description": "Not found"}},
)

@router.get("/")
def list_items():
    return []

@router.get("/{item_id}")
def get_item(item_id: int):
    return {"id": item_id}

# in main.py: app.include_router(router)

Statische Dateien

StaticFiles liefert ein Verzeichnis statischer Assets (Bilder, CSS, JS) unter einem URL-Präfix aus. Pro Verzeichnis einmal mounten. Für SPA-Frontends eine abschließende catch-all-Route mounten, die auf index.html zeigt. Statische Dateien umgehen das Routing-System aus Geschwindigkeitsgründen.

fastapi
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

# serve files from ./static at /static
app.mount("/static", StaticFiles(directory="static"), name="static")

# /static/logo.png -> ./static/logo.png
# /static/css/app.css -> ./static/css/app.css

Streaming-Response

StreamingResponse sendet eine Antwort, die in Chunks (Generator/Iterator) erzeugt wird, statt den ganzen Body im Speicher aufzubauen — ideal für große CSV-Exporte, File-Streaming oder SSE. media_type passend setzen, damit Clients den Stream korrekt behandeln.

fastapi
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import csv, io

app = FastAPI()

def iter_csv():
    output = io.StringIO()
    writer = csv.writer(output)
    writer.writerow(["id", "name"])
    for i in range(1000):
        writer.writerow([i, f"name-{i}"])
        yield output.getvalue()
        output.seek(0)
        output.truncate(0)

@app.get("/export.csv")
def export():
    return StreamingResponse(
        iter_csv(),
        media_type="text/csv",
        headers={"Content-Disposition": "attachment; filename=export.csv"},
    )

Eigene Route-Klasse

APIRoute abzuleiten erlaubt, jeden Route-Handler mit eigener Logik (Logging, Tracing, Timing) zu umwickeln, ohne jeden Endpunkt anzufassen. app.router.route_class setzen oder route_class an APIRouter übergeben. Der Handler läuft für jede passende Anfrage.

fastapi
from fastapi import FastAPI, Request, Response
from fastapi.routing import APIRoute
from typing import Callable

class LoggingRoute(APIRoute):
    def get_route_handler(self) -> Callable:
        original = super().get_route_handler()
        async def handler(request: Request) -> Response:
            print(f"-> {request.method} {request.url.path}")
            response = await original(request)
            print(f"<- {response.status_code}")
            return response
        return handler

app = FastAPI()
app.router.route_class = LoggingRoute

@app.get("/items")
def items():
    return {"items": []}

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.