【連載】Python FastAPI入門：第2回パスパラメータとクエリパラメータの使い分け

前回の記事では、FastAPIの概要とその驚異的な速さの秘密、そして環境構築から「Hello World」の表示までを解説しました。

前回の記事はこちら：【連載】Python FastAPI入門：第1回 FastAPIの特徴と「爆速」の理由

第2回となる今回は、Web APIを構築する上で欠かせない「ユーザーからデータを受け取る方法」について詳しく解説します。具体的には、パスパラメータとクエリパラメータの2つの使い分けと、FastAPI最大の武器である「型ヒントによる自動バリデーション」の実力を体験してみましょう。

パスパラメータ：リソースを特定する
- 実装コードの例
- 組み込みエンジニア視点での注目ポイント
クエリパラメータ：条件で絞り込む
- 実装コードの例
- デフォルト値と任意項目
パスとクエリの組み合わせ
Swagger UIでパラメータを試す
まとめ：第2回はここまで

パスパラメータ：リソースを特定する

パスパラメータは、URLのパス（階層）の一部としてデータを送る方法です。主に「特定のデータ（リソース）」を一意に指定する場合に使用されます。

例えば、ユーザーIDが「123」の情報を取得したい場合、URLは https://example.com/users/123 のようになります。

実装コードの例

FastAPIでは、Pythonのフォーマット文字列のような記法で簡単に記述できます。

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id, "message": f"ユーザーID {user_id} のデータを取得しました"}

組み込みエンジニア視点での注目ポイント

ここで user_id: int と型ヒントを書いているのが重要です。もしブラウザで /users/abc のように文字列を打ち込むと、FastAPIは即座にエラーを返します。

“http://127.0.0.1:8000/users/123″だと応答↓

“http://127.0.0.1:8000/users/aa”だとエラー！！

C言語などの静的型付け言語を扱っている方なら、「実行前に型が保証されている安心感」が理解いただけるはずです。関数の内部で isdigit() などのチェックを書く必要がありません。

クエリパラメータ：条件で絞り込む

クエリパラメータは、URLの末尾に ? から始まる形式でデータを送る方法です。主に「検索条件の指定」や「オプションのフラグ」として使用されます。

例えば、https://example.com/items?limit=10&offset=20 のような形式です。

実装コードの例

FastAPIでは、パスに含まれていない引数を関数に定義するだけで、自動的にクエリパラメータとして認識されます。

@app.get("/items/")
def read_items(skip: int = 0, limit: int = 10):
    # skip番目からlimit個のデータを返すイメージ
    return {"skip": skip, "limit": limit, "data": "アイテムリストの一部"}

デフォルト値と任意項目

上記の例では skip=0 のようにデフォルト値を設定しています。これにより、ユーザーがパラメータを指定しなかった場合でも安全に動作します。

パスとクエリの組み合わせ

実際の開発では、これらを組み合わせて使うことが非常に多いです。

@app.get("/users/{user_id}/items")
def get_user_items(user_id: int, q: str = None, short: bool = False):
    item = {"item_id": "Portal Gun", "owner_id": user_id}
    if q:
        item.update({"description": f"検索キーワード: {q}"})
    if not short:
        item.update({"detail": "これは非常に高度な技術で作られたポータルガンです。"})
    return item

user_id: パスパラメータ（必須）
q: クエリパラメータ（任意 / 文字列）
short: クエリパラメータ（任意 / 真偽値）

FastAPIは bool 型も賢く判別してくれるため、URLで short=1 や short=true と送るだけで、正しくPythonの True として処理してくれます。