FastAPIでクエリエンドポイントをマスターする

FastAPIとは何か

FastAPIは、Pythonのモダンで高速（高性能）なWebフレームワークで、非常に直感的で簡単に使用でき、標準のPython型ヒントを使用します。

FastAPIは、APIの開発を迅速化し、バグを減らし、直感的なエディタのサポートを提供します。これは、Python 3.6以降の型ヒントを基にしています。

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

高速: NodeJSやGoと同等の非常に高いパフォーマンス（StarletteとPydanticのおかげで）。
迅速な開発: 約2〜3倍の開発速度を提供します。開発者のエラーを減らし、直感的なエディタのサポートを提供します。
少ないバグ: 開発者のエラーを約40％減らします。Pythonの型システムを利用し、エディタのサポートを提供します。
直感的: 優れたエディタのサポート。自動補完がどこでも機能します。これにより、開発時間が大幅に短縮されます。
簡単: 設計が簡単で、使いやすく、ドキュメンテーションが充実しています。これにより、開発時間が大幅に短縮されます。
短い: コードの重複を最小限に抑えます。各パラメータに複数の機能を持たせることで、コード量を大幅に削減します。
堅牢: プロダクションでの使用を目的として設計されています。自動対話式ドキュメンテーションが付属しています。
基準に準拠: 完全にOpenAPI（以前はSwagger）とJSON Schemaの基準に準拠しています。
JSONベース: JSONリクエストとレスポンスを読み書きするためのPythonの型ヒントを使用します。
自動ドキュメンテーション: 直感的で使いやすい、自動対話式APIドキュメンテーション（Swagger UI）。
StarletteによるモダンなPython: FastAPIは、Starletteの非同期処理の恩恵を受けています。これにより、非常に高いパフォーマンスを実現しています。
Pydanticによるデータ検証: FastAPIは、Pydanticのデータ検証と直列化の恩恵を受けています。これにより、データの検証と直列化を簡単に行うことができます。

以上がFastAPIの概要です。これらの特徴により、FastAPIはPythonでのWeb開発を効率的に行うための強力なツールとなっています。次のセクションでは、FastAPIを使用してクエリエンドポイントをどのように作成するかについて詳しく説明します。

クエリパラメータの基本

クエリパラメータは、URLの一部であり、特定の情報をWebサーバーに送信するために使用されます。これらは通常、URLの末尾にある?記号の後に配置され、&記号で区切られます。

FastAPIでは、関数のパラメータとして直接クエリパラメータを宣言することができます。これにより、クエリパラメータの値が自動的に取得され、Pythonの変数として利用できます。

以下に、FastAPIを使用してクエリパラメータを取得する基本的な例を示します。

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
async def read_items(q: str = None):
    return {"query": q}

上記の例では、read_items関数はqという名前のクエリパラメータを持っています。このパラメータはオプショナルで、デフォルト値はNoneです。ユーザーがこのエンドポイントを/items/?q=somequeryのように呼び出すと、qの値は"somequery"になります。

FastAPIでは、クエリパラメータは常に文字列として解釈されます。しかし、型注釈を使用することで、クエリパラメータの値を他のデータ型（例えば、整数やブール値）に変換することも可能です。

以上がクエリパラメータの基本的な使い方です。次のセクションでは、クエリパラメータの型変換について詳しく説明します。

クエリパラメータの型変換

FastAPIでは、クエリパラメータの型変換を簡単に行うことができます。これはPythonの型ヒントを使用して行います。型ヒントは、関数のパラメータに対して期待するデータ型を指定するための構文です。

以下に、FastAPIを使用してクエリパラメータの型変換を行う基本的な例を示します。

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
async def read_items(q: str = None, price: float = None):
    return {"query": q, "price": price}

上記の例では、read_items関数はqという名前の文字列型のクエリパラメータと、priceという名前の浮動小数点型のクエリパラメータを持っています。ユーザーがこのエンドポイントを/items/?q=somequery&price=100.5のように呼び出すと、qの値は"somequery"に、priceの値は100.5になります。

FastAPIは、クエリパラメータの値を適切な型に自動的に変換します。もし型変換ができない場合（例えば、文字列を浮動小数点型に変換しようとした場合）、FastAPIは詳細なエラーを自動的に返します。

以上がクエリパラメータの型変換の基本的な使い方です。次のセクションでは、必須とオプショナルなクエリパラメータについて詳しく説明します。

必須とオプショナルなクエリパラメータ

FastAPIでは、クエリパラメータを必須またはオプショナルにすることができます。これは関数のパラメータのデフォルト値を設定することで制御します。

以下に、FastAPIを使用して必須とオプショナルなクエリパラメータを設定する基本的な例を示します。

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
async def read_items(q: str, price: float = None):
    return {"query": q, "price": price}

上記の例では、read_items関数はqという名前の必須のクエリパラメータと、priceという名前のオプショナルなクエリパラメータを持っています。ユーザーがこのエンドポイントを/items/?q=somequeryのように呼び出すと、qの値は"somequery"に、priceの値はNoneになります。

必須のクエリパラメータは、ユーザーがエンドポイントを呼び出す際に必ず指定しなければならないパラメータです。指定されていない場合、FastAPIは詳細なエラーメッセージを自動的に返します。

一方、オプショナルなクエリパラメータは、ユーザーがエンドポイントを呼び出す際に指定することも、指定しないことも可能なパラメータです。指定されていない場合、そのパラメータのデフォルト値が使用されます。

以上が必須とオプショナルなクエリパラメータの基本的な使い方です。次のセクションでは、複数のパスパラメータとクエリパラメータについて詳しく説明します。

複数のパスパラメータとクエリパラメータ

FastAPIでは、複数のパスパラメータとクエリパラメータを同時に使用することができます。これにより、エンドポイントが必要とするさまざまな情報を柔軟に受け取ることが可能になります。

以下に、FastAPIを使用して複数のパスパラメータとクエリパラメータを設定する基本的な例を示します。

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query": q}

上記の例では、read_item関数はitem_idという名前のパスパラメータと、qという名前のクエリパラメータを持っています。ユーザーがこのエンドポイントを/items/5?q=somequeryのように呼び出すと、item_idの値は5に、qの値は"somequery"になります。

パスパラメータは、URLのパス部分に含まれるパラメータで、{}で囲まれています。これらのパラメータは、URLの一部として直接指定されます。

一方、クエリパラメータは、URLの末尾にある?記号の後に配置され、&記号で区切られます。

FastAPIは、これらのパスパラメータとクエリパラメータを適切に解析し、関数のパラメータとして提供します。これにより、エンドポイントは必要な情報を簡単に取得できます。

以上が複数のパスパラメータとクエリパラメータの基本的な使い方です。次のセクションでは、FastAPIにおけるクエリパラメータの実用例について詳しく説明します。

FastAPIにおけるクエリパラメータの実用例

FastAPIを使用してクエリパラメータを活用することで、APIエンドポイントが柔軟にユーザーからの入力を受け取ることが可能になります。以下に、FastAPIにおけるクエリパラメータの実用例をいくつか示します。

商品検索エンドポイント

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
async def search_items(q: str = None):
    # データベースから`q`を含む商品を検索
    # ...
    return {"items": items, "query": q}

上記の例では、/items/エンドポイントはqという名前のクエリパラメータを受け取り、それを使用して商品を検索します。ユーザーがこのエンドポイントを/items/?q=bookのように呼び出すと、qの値は"book"になり、その値を使用して商品を検索します。

ページネーション付き商品一覧エンドポイント

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
async def read_items(page: int = 1, per_page: int = 20):
    # データベースから商品を取得
    # `page`と`per_page`を使用して結果をページネーション
    # ...
    return {"page": page, "per_page": per_page, "items": items}

上記の例では、/items/エンドポイントはpageとper_pageという名前のクエリパラメータを受け取り、それらを使用して商品の一覧をページネーションします。ユーザーがこのエンドポイントを/items/?page=2&per_page=30のように呼び出すと、pageの値は2に、per_pageの値は30になり、その値を使用して商品の一覧をページネーションします。

以上がFastAPIにおけるクエリパラメータの実用例です。これらの例からわかるように、クエリパラメータはAPIエンドポイントがユーザーからの入力を柔軟に受け取るための強力なツールとなります。FastAPIの型システムと自動バリデーション機能を活用することで、これらのクエリパラメータの取り扱いをさらに簡単かつ安全にすることが可能です。次のセクションでは、FastAPIにおけるクエリパラメータの実用例について詳しく説明します。