FastAPIでリクエストとレスポンスをカスタマイズ

プログラミング

2026.01.28

FastAPIにおけるリクエストとレスポンスのカスタマイズ：詳細と応用

FastAPIにおけるリクエストとレスポンスのカスタマイズ：詳細と応用

FastAPIは、Pythonの非同期Webフレームワークとして、その高いパフォーマンスと使いやすさから多くの開発者に支持されています。特に、リクエストとレスポンスのカスタマイズ機能は、APIの柔軟性と表現力を大きく向上させます。ここでは、FastAPIにおけるリクエストとレスポンスのカスタマイズについて、より深く掘り下げ、具体的な応用例と共に解説します。

リクエストのカスタマイズ

FastAPIでは、Pydanticモデルを利用することで、リクエストボディの構造、型、バリデーションを宣言的に定義できます。これにより、APIは意図しないデータ型や不正な値を受け付けることを防ぎ、堅牢性を高めます。

パスパラメータとクエリパラメータの活用

APIエンドポイントのURLに含まれるパスパラメータや、URLの?以降に記述されるクエリパラメータは、リクエストの基本的な情報伝達手段です。FastAPIでは、これらのパラメータを関数引数として直接受け取ることができます。

例えば、ユーザーIDを指定して特定のユーザー情報を取得するAPIを考えます。

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
def read_user(user_id: int):
    return {"user_id": user_id, "username": f"User_{user_id}"}

この例では、user_idはパスパラメータとして定義され、自動的にint型に変換されます。型ヒントを指定することで、FastAPIは自動的に型チェックとドキュメント生成を行います。

クエリパラメータも同様に、関数引数として定義できます。

@app.get("/items/")
def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

skipとlimitはクエリパラメータとなり、デフォルト値も設定できます。これにより、APIは柔軟なデータ取得を可能にします。

リクエストボディ：Pydanticモデルによる構造化

POSTやPUTリクエストなどで送信されるリクエストボディは、通常、JSON形式で送られてきます。FastAPIでは、Pydanticモデルを定義することで、このJSONデータの構造を明確にし、バリデーションを自動化します。

新しいアイテムを作成するAPIを例に見てみましょう。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None

@app.post("/items/")
def create_item(item: Item):
    item_dict = item.dict()
    if item.tax:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

ここでは、ItemというPydanticモデルを定義しました。nameとpriceは必須項目であり、descriptionとtaxはオプションです。FastAPIは、このItemモデルに基づいてリクエストボディを解析し、バリデーションを実行します。不正なデータが送信された場合、FastAPIは自動的にエラーレスポンスを返します。

カスタムバリデーションとロジック

Pydanticモデルのフィールドにバリデータ関数を定義することで、より複雑なカスタムバリデーションを実装できます。

例えば、priceが正の値であることを保証したい場合、以下のように記述できます。

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, validator

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

    @validator('price')
    def price_must_be_positive(cls, value):
        if value <= 0:
            raise ValueError('Price must be positive')
        return value

app = FastAPI()

@app.post("/products/")
def create_product(product: Product):
    return product

このvalidatorデコレーターは、priceフィールドの値がpositiveであることを検証します。もし条件を満たさない場合、ValueErrorが送出され、FastAPIは適切なエラーレスポンスを生成します。

ヘッダーとCookieの利用

リクエストヘッダーやCookieも、APIで情報をやり取りするための重要な要素です。FastAPIでは、HeaderやCookieパラメータを利用してこれらを簡単に扱うことができます。

from fastapi import FastAPI, Header, Cookie

app = FastAPI()

@app.get("/headers/")
def get_headers(user_agent: str = Header(None), secret_key: str | None = Cookie(None)):
    return {"user_agent": user_agent, "secret_key": secret_key}

ここでは、user_agentヘッダーとsecret_keyCookieを取得しています。これらの値は、クライアントからのリクエストに含まれている必要があります。オプションとしてNoneを指定することで、ヘッダーやCookieが存在しない場合でもエラーにならないようにできます。

レスポンスのカスタマイズ

FastAPIは、レスポンスの構造化とフォーマットを柔軟に制御する機能を提供します。これにより、APIはクライアントが必要とする情報を効率的かつ分かりやすい形式で提供できます。

レスポンスモデル：Pydanticモデルによる構造化

リクエストと同様に、レスポンスもPydanticモデルを使用して構造化できます。これにより、APIから返されるデータの形式が明確になり、クライアントは期待通りのデータを受け取ることができます。

from fastapi import FastAPI
from pydantic import BaseModel

class User(BaseModel):
    username: str
    email: str | None = None
    full_name: str | None = None

app = FastAPI()

@app.get("/users/{user_id}", response_model=User)
def read_user_profile(user_id: int):
    # データベースなどからユーザー情報を取得する処理
    return {"username": f"user{user_id}", "email": f"user{user_id}@example.com"}

この例では、response_model=Userを指定することで、read_user_profile関数が返すレスポンスはUserモデルの構造に従うことをFastAPIに伝えています。FastAPIは、返された辞書をUserモデルに変換し、バリデーションを実行します。これにより、APIのドキュメント（Swagger UI）にもレスポンスの構造が正確に反映されます。

ステータスコードの制御

APIのレスポンスは、HTTPステータスコードによってその結果を示します。FastAPIでは、status_codeパラメータやHTTPExceptionを使用して、ステータスコードを柔軟に制御できます。

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

@app.post("/items_status/", status_code=status.HTTP_201_CREATED)
def create_item_with_status():
    return {"message": "Item created successfully"}

@app.get("/resource/{resource_id}")
def get_resource(resource_id: int):
    if resource_id == 404:
        raise HTTPException(status_code=404, detail="Resource not found")
    return {"resource_id": resource_id, "data": "Some data"}

最初の例では、status_code=status.HTTP_201_CREATEDを指定することで、リクエストが成功した際に201 Createdステータスコードを返します。二番目の例では、特定の条件（resource_id == 404）でHTTPExceptionを発生させることで、クライアントに404 Not Foundエラーを通知します。

レスポンスヘッダーの設定

APIレスポンスにカスタムヘッダーを追加することで、クライアントに付加的な情報を提供したり、キャッシュ制御などを行ったりできます。

from fastapi import FastAPI, Response

app = FastAPI()

@app.get("/custom-header/")
def get_with_custom_header(response: Response):
    response.headers["X-Custom-Header"] = "My Value"
    return {"message": "Response with custom header"}

この例では、Responseオブジェクトを関数引数として受け取り、そのheaders属性にカスタムヘッダーを追加しています。FastAPIは、このResponseオブジェクトを元にレスポンスを生成します。

レスポンスのフィルタリングとインクルード/エクスクルード

Pydanticモデルのresponse_modelを使用する際に、includeやexcludeパラメータを利用して、レスポンスに含めるフィールドや除外するフィールドを制御できます。

from fastapi import FastAPI
from pydantic import BaseModel

class UserWithSensitiveInfo(BaseModel):
    username: str
    email: str
    password: str

class UserPublic(BaseModel):
    username: str
    email: str

app = FastAPI()

@app.post("/users/", response_model=UserPublic)
def create_user(user: UserWithSensitiveInfo):
    return user

この例では、create_userエンドポイントはUserWithSensitiveInfoモデルを受け取りますが、レスポンスとして返すのはUserPublicモデルのみです。これにより、パスワードのような機密情報がレスポンスに含まれないように制御できます。

カスタムレスポンス

Responseオブジェクトを直接返すことで、JSON以外の形式（HTML, XMLなど）や、より細かいレスポンスの制御が可能になります。

from fastapi import FastAPI, Response
from starlette.responses import HTMLResponse

app = FastAPI()

@app.get("/html-response/", response_class=HTMLResponse)
def get_html():
    return "Hello, HTML!"

ここでは、response_class=HTMLResponseを指定することで、関数が返す文字列をHTMLとしてクライアントに返します。これは、APIがHTMLコンテンツを生成する場合に非常に便利です。

高度なカスタマイズと応用

FastAPIのカスタマイズ機能は、単にリクエストとレスポンスを構造化するだけでなく、APIの振る舞いをより洗練させることができます。

依存性注入（Dependency Injection）

FastAPIの強力な機能の一つに依存性注入があります。これは、リクエスト処理に必要なリソース（データベース接続、認証情報など）を、APIエンドポイント関数とは独立して管理・提供する仕組みです。これにより、コードの再利用性が高まり、テストが容易になります。

例えば、データベース接続を依存性として注入する場合、以下のように記述できます。

from fastapi import FastAPI, Depends
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

# SQLAlchemyの設定（例）
SQLALCHEMY_DATABASE_URL = "sqlite:///./sql_app.db"
engine = create_engine(SQLALCHEMY_DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

app = FastAPI()

@app.get("/items_db/")
def read_items_from_db(db: Session = Depends(get_db)):
    # dbオブジェクトを使用してデータベース操作を行う
    return {"message": "Accessed database"}

ここで、Depends(get_db)は、get_db関数が返すデータベースセッションをdb引数に注入します。APIエンドポイント関数は、データベース接続の詳細を意識することなく、クリーンなコードでロジックを記述できます。

例外処理とグローバルエラーハンドリング

FastAPIは、例外処理をカスタマイズするためのメカニズムも提供します。HTTPException以外にも、カスタム例外クラスを定義し、それらをハンドリングするエンドポイントを登録することで、API全体のエラーレスポンスを一元管理できます。

from fastapi import FastAPI, Request, status
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content={"detail": exc.errors()},
    )

この例では、RequestValidationErrorが発生した場合に、カスタムのJSONResponseを返すように設定しています。これにより、API全体で統一されたエラーレスポンスフォーマットを提供できます。

ミドルウェアの活用

FastAPI（Starletteベース）は、ミドルウェアをサポートしています。ミドルウェアは、リクエストがエンドポイントに到達する前、またはレスポンスがクライアントに送信される前に実行される処理です。ログ記録、認証、CORS設定などに利用できます。

from fastapi import FastAPI
from starlette.middleware.cors import CORSMiddleware

app = FastAPI()

origins = [
    "http://localhost:3000",
    "https://your-frontend.com",
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

この例では、CORS（Cross-Origin Resource Sharing）を有効にするためのミドルウェアを追加しています。これにより、異なるドメインからAPIへのアクセスを許可することができます。

まとめ

FastAPIにおけるリクエストとレスポンスのカスタマイズは、Pydanticモデル、型ヒント、そしてFastAPI独自の機能（依存性注入、例外処理、ミドルウェアなど）を組み合わせることで、強力かつ柔軟なAPI開発を可能にします。これらの機能を効果的に活用することで、APIの堅牢性、保守性、そして開発効率を大幅に向上させることができます。リクエストデータのバリデーション、レスポンスの構造化、エラーハンドリングの統一、そして外部リソースとの連携など、API開発のあらゆる側面で、FastAPIのカスタマイズ機能は開発者を強力にサポートします。