Wie funktionieren Pfad- und Abfrageparameter?

Question

Accepted Answer

FastAPI extrahiert **Pfadparameter** (Teil des URL-Pfads) und **Abfrageparameter** (nach `?`) aus Funktionsargumenten und konvertiert und validiert sie automatisch unter Verwendung von Typannotationen.

## Pfadparameter — Teil der URL

```python
@app.get("/items/{item_id}")        # {item_id} in the path
def get_item(item_id: int):          # matched by NAME; `int` converts & validates
    return {"item_id": item_id}
# GET /items/5 → item_id = 5 (int).  GET /items/abc → 422 error (not an int)
```

Ein Funktionsparameter, dessen Name einen `{placeholder}` im Pfad enthält, wird zum **Pfadparameter**. Die Typannotation (`int`) konvertiert die Zeichenkette aus der URL automatisch und gibt einen eindeutigen Fehler 422 zurück, wenn sie nicht übereinstimmt.

## Abfrageparameter — alles andere

```python
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, q: str | None = None):
    # parameters NOT in the path become QUERY parameters
    # GET /items?skip=20&limit=5&q=phone → skip=20, limit=5, q="phone"
    return {"skip": skip, "limit": limit, "q": q}
```

Funktionsparameter, die **nicht** im Pfad sind, werden zu **Abfrageparametern**. Ein Standardwert macht sie optional (`skip: int = 0`); `str | None = None` macht einen nullbaren optionalen Abfrageparameter. Ohne Standardwert sind sie erforderlich.

## Erforderlich vs. optional

```python
def search(q: str):              # REQUIRED query param (no default) → ?q=... must be present
def search(q: str = ""):          # optional, defaults to ""
def search(q: str | None = None): # optional, defaults to None
```

## Beide kombinieren

```python
@app.get("/users/{user_id}/items")
def user_items(user_id: int, limit: int = 10):
    # user_id = path param, limit = query param — distinguished by the path
```

## Warum es wichtig ist

Pfad- und Abfrageparameter sind die Art und Weise, wie Endpunkte Eingaben aus der URL empfangen — grundlegend für nahezu jede API-Route (Abrufen einer Ressource nach ID, Filtern, Paginierung, Suche).

FastAPIs Ansatz ist elegant und ein Hauptgrund für seine Produktivität: Durch einfache Deklaration von typisierten Funktionsparametern erhalten Sie automatische Extraktion, **Typkonvertierung**, **Validierung** (mit eindeutigen Fehlern 422 bei ungültiger Eingabe) und Erforderlich-vs-Optional-Semantik (über Standardwerte) — alles abgeleitet von Standard-Python-Typannotationen, ohne manuelles Parsing.

Das Verständnis der Unterscheidung (Pfadparameter kommen von `{placeholders}`, alles andere ist ein Abfrageparameter) und wie Standardwerte die Optionalität kontrollieren, ist wesentliches Alltagswissen für den Aufbau von FastAPI-Endpunkten.