Hoe werken pad- en queryparameters?

Question

Accepted Answer

FastAPI extraheert **padparameters** (onderdeel van het URL-pad) en **queryparameters** (na `?`) uit functieargumenten, met behulp van type hints om ze automatisch om te zetten en te valideren.

## Waarom het belangrijk is

Pad- en queryparameters zijn hoe eindpunten invoer van de URL ontvangen — fundamenteel voor vrijwel elke API-route (een resource ophalen op basis van id, filteren, pagineren, zoeken).

De benadering van FastAPI is elegant en een belangrijke reden waarom het productief is: het eenvoudig declareren van getypeerde functieargumenten geeft u automatische extractie, **typeconversie**, **validatie** (met duidelijke 422-fouten bij slechte invoer) en semantiek voor vereist-versus-optioneel (via standaardwaarden) — allemaal afgeleid van standaard Python-typehints, zonder handmatig parseren.

Het onderscheid begrijpen (padparameters komen uit `{placeholders}`, alles anders is een queryparameter) en hoe standaardwaarden optionaliteit bepalen, is essentiële dagelijkse kennis voor het bouwen van FastAPI-eindpunten.

## Padparameters — onderdeel van de 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)
```

Een functieparameter waarvan de naam overeenkomt met een `{placeholder}` in het pad wordt een **padparameter**. De type hint (`int`) converteert de string van de URL automatisch en retourneert een duidelijke 422-fout als deze niet overeenkomt.

## Queryparameters — al het 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}
```

Functieparameters **niet** in het pad worden **queryparameters**. Een standaardwaarde maakt ze optioneel (`skip: int = 0`); `str | None = None` maakt een nullable optionele queryparameter. Zonder standaardwaarde zijn ze vereist.

## Vereist versus optioneel

```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 combineren

```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
```