エンドポイントの追加

サーバは--reloadオプションで起動しているため、main.pyを変更して保存するたびにサーバが自動的に再起動されます。ここからは、さまざまな種類のエンドポイントを追加しながら、FastAPIの機能を学んでいきます。

1. 複数のエンドポイントの定義

1つのアプリケーションに複数のエンドポイントを定義できます。main.pyに以下のエンドポイントを追加します。

@app.get("/about")
def about():
    return {"app_name": "FastAPI Demo", "version": "1.0.0"}

ファイルを保存すると、サーバが自動的に再起動されます。curlコマンドで確認します。

curl http://localhost:8000/about

以下のような結果が表示されます。

{"app_name":"FastAPI Demo","version":"1.0.0"}

/にアクセスするとroot()関数、/aboutにアクセスするとabout()関数がそれぞれ実行されます。このように、デコレータのパスを変えることで、URLごとに異なる処理を割り当てることができます。

2. パスパラメータ

2.1 パスパラメータとは

パスパラメータは、URLのパスの一部をパラメータとして受け取る仕組みです。基本的な構文は以下のとおりです。

@app.get("/パス/{パラメータ名}")
def 関数名(パラメータ名: 型):
    return データ

パスの中に{パラメータ名}を含めると、その部分がパラメータとして関数の引数に渡されます。

実際に試してみましょう。main.pyに以下のエンドポイントを追加します。

@app.get("/hello/{name}")
def hello(name: str):
    return {"message": f"こんにちは、{name}さん!"}

{name}がパスパラメータです。URLの/hello/の後に指定した値が、関数の引数nameに渡されます。: strの型ヒントにより、FastAPIがパラメータを文字列型として受け取ります。

curl http://localhost:8000/hello/太郎

以下のような結果が表示されます。

{"message":"こんにちは、太郎さん!"}

URLの太郎の部分がパスパラメータとして関数に渡され、f"こんにちは、{name}さん!"によって文字列に組み込まれてレスポンスに反映されています。

2.2 パスパラメータの型によるバリデーション

パスパラメータにはint型を指定することもできます。main.pyに以下のエンドポイントを追加します。

@app.get("/items/{item_id}")
def get_item(item_id: int):
    return {"item_id": item_id, "message": f"アイテム{item_id}の情報です"}

item_id: intと型ヒントを指定することで、FastAPIがパスパラメータを自動的に整数型に変換します。

整数を指定してリクエストを送信します。

curl http://localhost:8000/items/3

以下のようなレスポンスが返されます。

{"item_id":3,"message":"アイテム3の情報です"}

パスパラメータの3が整数として関数に渡されています。

次に、整数ではない文字列を指定した場合の動作を確認します。

curl http://localhost:8000/items/abc

以下のようなレスポンスが返されます。

{"detail":[{"type":"int_parsing","loc":["path","item_id"],"msg":"Input should be a valid integer, unable to parse string as an integer","input":"abc"}]}

item_id: intの型ヒントに基づいて、FastAPIが自動的にバリデーションを行い、整数に変換できない値が渡された場合はエラーレスポンスを返しています。このように、型ヒントを指定するだけでバリデーションが自動化されるのがFastAPIの特徴です。

3. クエリパラメータ

クエリパラメータは、URLの?以降にキー=値の形式で指定するパラメータです。基本的な構文は以下のとおりです。

@app.get("/パス")
def 関数名(パラメータ名: 型 = デフォルト値):
    return データ

パスパラメータと異なり、URLのパスには含めず、関数の引数として定義します。デフォルト値を指定するとオプションパラメータになり、省略した場合はデフォルト値が使用されます。

実際に試してみましょう。main.pyに以下のエンドポイントを追加します。

@app.get("/search")
def search(q: str, limit: int = 10):
    return {"query": q, "limit": limit}

qはデフォルト値がないため必須パラメータ、limitはデフォルト値10が設定されているためオプションパラメータです。

両方のパラメータを指定して確認します。

curl "http://localhost:8000/search?q=Python&limit=5"

以下のようなレスポンスが返されます。

{"query":"Python","limit":5}

limitを省略した場合はデフォルト値の10が使用されます。

curl "http://localhost:8000/search?q=FastAPI"

以下のようなレスポンスが返されます。

{"query":"FastAPI","limit":10}
📝 パスパラメータとクエリパラメータの違い
パスパラメータはURLのパスの一部(/hello/太郎)、クエリパラメータはURLの?以降(/search?q=Python)で値を指定します。一般的に、リソースを特定する場合はパスパラメータ、検索条件やオプションを指定する場合はクエリパラメータが使われます。

4. リクエストボディ

POSTやPUTメソッドでデータを送信する場合、リクエストのボディにJSONデータを格納します。FastAPIでは、Pydanticモデルを使ってリクエストボディのデータ構造を定義します。

まず、main.pyの先頭のインポート文を以下のように変更します。

from fastapi import FastAPI
from pydantic import BaseModel

from pydantic import BaseModelは、冒頭で紹介したデータバリデーションライブラリPydanticからBaseModelクラスをインポートしています。BaseModelを継承したクラスを定義することで、リクエストボディのデータ構造とバリデーションルールを宣言的に記述できるようになります。

次に、app = FastAPI()の下にPydanticモデルを追加します。

class Item(BaseModel):
    name: str
    price: float

BaseModelを継承したクラスを定義し、フィールドに型ヒントを指定します。nameは文字列型、priceは浮動小数点型の必須フィールドです。リクエストボディのJSONデータがこのモデルの構造と一致しない場合、FastAPIが自動的にバリデーションエラーを返します。

エンドポイントを追加します。

@app.post("/items", status_code=201)
def create_item(item: Item):
    return {"message": "アイテムを作成しました", "item": {"name": item.name, "price": item.price}}

関数の引数にPydanticモデルの型ヒント(item: Item)を指定すると、リクエストボディのJSONデータが自動的にモデルに変換され、item.nameやitem.priceでアクセスできます。status_code=201は、リソースの作成に成功したことを示すHTTPステータスコード201 Createdをレスポンスに設定します。

curl -X POST http://localhost:8000/items \
  -H "Content-Type: application/json" \
  -d '{"name": "ノート", "price": 250}'

以下のようなレスポンスが返されます。

{"message":"アイテムを作成しました","item":{"name":"ノート","price":250.0}}

-X POSTでHTTPメソッドを指定し、-Hでリクエストヘッダ(Content-Type)、-dでリクエストボディ(JSON)を指定しています。

必須フィールドのnameを省略した場合の動作も確認してみましょう。

curl -X POST http://localhost:8000/items \
  -H "Content-Type: application/json" \
  -d '{"price": 250}'

以下のような結果になると思います。

{"detail":[{"type":"missing","loc":["body","name"],"msg":"Field required","input":{"price":250}}]}

Pydanticによるバリデーションが自動的に行われ、nameフィールドが必須であることを示すエラーが返されます。