エンドポイントの追加
サーバは--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フィールドが必須であることを示すエラーが返されます。