パスパラメータとクエリパラメータはどのように機能しますか?

Question

Accepted Answer

FastAPIは、**パスパラメータ**（URLパスの一部）と**クエリパラメータ**（`?`の後）を関数の引数から抽出し、型ヒントを使用して自動的に変換および検証します。

## パスパラメータ — 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)
```

パス内の `{placeholder}` に名前が一致する関数パラメータは、**パスパラメータ**になります。型ヒント（`int`）はURLからの文字列を自動的に変換し、一致しない場合は明確な422エラーを返します。

## クエリパラメータ — その他すべて

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

パスにない関数パラメータは**クエリパラメータ**になります。デフォルト値によってオプションになります（`skip: int = 0`）。`str | None = None` はnullableなオプションクエリパラメータです。デフォルトがない場合は必須です。

## 必須 vs オプション

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

## 両方を組み合わせる

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

## なぜ重要なのか

パスパラメータとクエリパラメータは、エンドポイントがURLから入力を受け取る方法です。ほぼすべてのAPIルート（IDでリソースを取得、フィルター、ページネーション、検索）の基本です。

FastAPIのアプローチは優雅で、その生産性の重要な理由です。型付き関数パラメータを宣言するだけで、自動抽出、**型変換**、**検証**（不正な入力に対する明確な422エラー）、および必須対オプションのセマンティクス（デフォルト値を介して）が得られます。これらはすべて標準的なPython型ヒントから導出され、手動解析は不要です。

パスパラメータは `{placeholders}` から来ること、その他すべてはクエリパラメータであること、およびデフォルト値がオプション性をどのように制御するかを理解することは、FastAPIエンドポイントを構築するための日常の必須知識です。