FastAPIのパスパラメータとクエリパラメータについて

FastAPIとは

FastAPIは、Pythonの非常に高速な（高性能）、使いやすい、モダンな、高速（高性能）なWebフレームワークです。これは、Python 3.6以降の型ヒントに基づいています。

FastAPIの主な特徴は次のとおりです:

• 高速: NodeJSやGoと同等の非常に高速なパフォーマンス（StarletteとPydanticのおかげです）。
• 高速なコーディング: 開発者の生産性を約2倍から3倍に向上させます。開発時間を大幅に短縮し、バグを減らし、開発者が直感的にコードを書くことを可能にします。
• 少ないバグ: デベロッパーが意図しないエラーやバグを少なくするためのシステム。エディタのサポートも強力です。
• 直感的: 優れたエディタのサポート。自動補完が非常に強力で、ほとんど必要な場所で使用できます。
• 簡単: 高度に直感的で使いやすい設計。ドキュメンテーションを読む時間を大幅に短縮します。
• 短い: コードの重複を最小限に抑えます。各パラメータの複数の機能を最大限に活用します。これにより、バグが少なくなります。
• 堅牢: プロダクションでの使用を目的としたコード。自動対話式ドキュメンテーションを備えています。
• 基準に準拠: 完全にオープンスタンダードに基づいています：OpenAPI（以前はSwaggerとして知られていました）とJSON Schema。
• JSONベース: JSONリクエストとレスポンスを使用します。Pydanticモデルを使用してデータの検証、直列化、ドキュメンテーションを行います。
• 自動ドキュメンテーション: 直感的で使いやすい、自動対話式APIドキュメンテーション（Swagger UI）。
• 認証と認可: OAuth2の「パスワードフロー」を含む完全なサポート、ヘッダー、クッキー、OAuth2スコープ、ユーザーのロールと許可など。

パスパラメータの基本

FastAPIでは、パスパラメータを使用して動的なURLを作成することができます。これは、特定のリソースにアクセスするための一般的な方法です。

例えば、以下のようなルートを定義することができます:

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

この例では、item_idはパスパラメータです。URLの一部として渡され、関数の引数として使用されます。この場合、item_idは整数型（int）であると宣言されています。

FastAPIは、型宣言を使用して、受け取ったパラメータの値を自動的に変換します。したがって、上記の例では、item_idは整数として扱われます。

また、FastAPIは、パスパラメータが必須であることを自動的に認識します。したがって、このパラメータがURLに含まれていない場合、FastAPIはエラーを返します。

パスパラメータは、リソースの特定のインスタンスにアクセスするため、またはリソース間の階層的な関係を表現するためによく使用されます。例えば、/users/{user_id}/items/{item_id}のようなURLは、特定のユーザーが所有する特定のアイテムにアクセスすることを可能にします。このようなURL設計は、RESTfulなAPI設計の一般的なパターンです。

クエリパラメータの基本

クエリパラメータは、URLの末尾に ? の後に追加され、キーと値のペアで表されます。これらは、特定のリソースをフィルタリングしたり、ソートしたり、ページネーションを制御したりするためによく使用されます。

FastAPIでは、関数の引数としてクエリパラメータを簡単に定義できます。例えば、以下のようなルートを定義することができます:

from typing import Optional

@app.get("/items/")
async def read_items(q: Optional[str] = None):
    if q:
        return {"item": q}
    return {"item": "not found"}

この例では、qはクエリパラメータです。このパラメータはオプショナルで、デフォルト値はNoneです。ユーザーがこのパラメータをURLに含めてリクエストを送ると、その値が関数の引数qに渡されます。

FastAPIは、型宣言を使用して、受け取ったパラメータの値を自動的に変換します。したがって、上記の例では、qは文字列として扱われます。

また、FastAPIは、クエリパラメータがオプショナルであることを自動的に認識します。したがって、このパラメータがURLに含まれていない場合でも、FastAPIはエラーを返しません。

クエリパラメータは、リソースの特定のインスタンスにアクセスするのではなく、リソースの集合をフィルタリングしたりソートしたりするためによく使用されます。例えば、/items/?sort=priceのようなURLは、アイテムを価格順にソートして返すことを可能にします。このようなURL設計は、RESTfulなAPI設計の一般的なパターンです。

パスパラメータとクエリパラメータの違い

パスパラメータとクエリパラメータは、URL内で異なる情報を伝達するための2つの主要な方法です。しかし、それぞれが使用される状況と目的は異なります。

パスパラメータ

パスパラメータは、URLのパス部分に含まれ、特定のリソースを一意に識別します。これは、リソースの階層的な関係を表現するためによく使用されます。例えば、/users/{user_id}/items/{item_id}のようなURLは、特定のユーザーが所有する特定のアイテムにアクセスすることを可能にします。

クエリパラメータ

一方、クエリパラメータは、URLの末尾に ? の後に追加され、キーと値のペアで表されます。これらは、特定のリソースをフィルタリングしたり、ソートしたり、ページネーションを制御したりするためによく使用されます。例えば、/items/?sort=priceのようなURLは、アイテムを価格順にソートして返すことを可能にします。

まとめ

したがって、パスパラメータとクエリパラメータの主な違いは、パスパラメータがURLの一部としてリソースを一意に識別するのに対し、クエリパラメータはURLの末尾に追加され、リソースの集合を操作するために使用されるということです。これらは、APIの設計と機能性において重要な役割を果たします。どちらを使用するかは、特定の状況と要件によります。

FastAPIでのパスパラメータとクエリパラメータの使用例

FastAPIでは、パスパラメータとクエリパラメータを簡単に使用することができます。以下に、それぞれの使用例を示します。

パスパラメータの使用例

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

上記のコードでは、item_idがパスパラメータとして定義されています。このitem_idはURLの一部として渡され、関数の引数として使用されます。

クエリパラメータの使用例

from typing import Optional
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
async def read_items(q: Optional[str] = None):
    if q:
        return {"item": q}
    return {"item": "not found"}

上記のコードでは、qがクエリパラメータとして定義されています。このqはURLの末尾に ? の後に追加され、その値が関数の引数qに渡されます。

これらの例からわかるように、FastAPIでは型ヒントを使用してパスパラメータとクエリパラメータを簡単に定義し、扱うことができます。これにより、APIの設計と実装が大幅に簡素化されます。また、FastAPIはこれらのパラメータを自動的に検証し、ドキュメンテーション化します。これにより、APIの安全性とメンテナンス性が向上します。

まとめ

この記事では、PythonのFastAPIフレームワークでのパスパラメータとクエリパラメータの使用について詳しく説明しました。

まず、FastAPIとその主な特徴について紹介しました。次に、パスパラメータとクエリパラメータの基本的な概念とそれぞれの使用例を示しました。また、パスパラメータとクエリパラメータの違いについても説明しました。

FastAPIは、パスパラメータとクエリパラメータを簡単に定義し、扱うことができる強力なフレームワークです。これにより、APIの設計と実装が大幅に簡素化され、安全性とメンテナンス性が向上します。

これらの知識を活用して、より効率的で使いやすいAPIを設計し、開発することができます。FastAPIのパワフルな機能を最大限に活用して、素晴らしいWebアプリケーションを作成しましょう！