FastAPIは、パスパラメータ(URLパスの一部)とクエリパラメータ(?の後)を関数の引数から抽出し、型ヒントを使用して自動的に変換および検証します。
パスパラメータ — URLの一部
python
():
{: item_id}
パス内の {placeholder} に名前が一致する関数パラメータは、パスパラメータになります。型ヒント(int)はURLからの文字列を自動的に変換し、一致しない場合は明確な422エラーを返します。
@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なオプションクエリパラメータです。デフォルトがない場合は必須です。
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
@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エンドポイントを構築するための日常の必須知識です。