FastAPIドキュメント入門：API開発を始めるための第一歩

By /

FastAPI ドキュメント入門：API 開発を始めるための第一歩

Web API (Application Programming Interface) は、現代のソフトウェア開発において不可欠な要素です。アプリケーション同士がデータを交換し、連携するための共通言語として機能し、マイクロサービスアーキテクチャの実現や、フロントエンドとバックエンドの分離、モバイルアプリケーションとの連携など、様々な用途で利用されています。

Web API を構築するためのフレームワークは数多く存在しますが、近年注目を集めているのが Python 製の FastAPI です。FastAPI は、その名の通り、高速 (Fast) に API を構築できるだけでなく、ドキュメントの自動生成、型ヒントによる開発効率の向上、堅牢なバリデーション機能など、開発者が求める多くの機能を提供します。

本記事では、FastAPI を用いた API 開発の基礎を、ドキュメントを読み解きながら丁寧に解説します。FastAPI の基本的な概念、インストール方法、API の定義、リクエストの処理、データのバリデーション、セキュリティ対策、そしてドキュメントの自動生成まで、FastAPI を使い始めるための第一歩を、詳細なコード例と解説とともに提供します。

1. FastAPI とは？ なぜ FastAPI を選ぶのか

FastAPI は、Python 3.6+ をベースに開発されたモダンな Web API フレームワークです。その特徴は、以下の点に集約されます。

  • 高速性: ASGI (Asynchronous Server Gateway Interface) に対応しており、高パフォーマンスな API を実現します。Starlette と Uvicorn を基盤としており、Node.js や Go に匹敵するパフォーマンスを発揮します。
  • 高速な開発: 型ヒント (Type Hints) を活用することで、開発効率を大幅に向上させます。自動補完、エラー検出、ドキュメントの自動生成など、開発を支援する機能が充実しています。
  • 少ないバグ: 型ヒントによる厳密な型チェックにより、実行時エラーを未然に防ぎます。バリデーション機能も充実しており、安全な API を構築できます。
  • 使いやすさ: 簡潔な構文と直感的な API 設計により、学習コストが低く、容易に API を構築できます。
  • 標準ベース: OpenAPI (Swagger UI) と JSON Schema を標準でサポートしており、API ドキュメントの自動生成、API クライアントの自動生成などが可能です。
  • Production Ready: 大規模なアプリケーションにも耐えうる設計であり、信頼性とスケーラビリティに優れています。

これらの特徴から、FastAPI は、以下のような場合に特に適しています。

  • 高パフォーマンスが求められる API
  • 短期間で効率的に開発する必要がある API
  • 型安全性が重要視される API
  • OpenAPI 仕様に準拠した API

他の Python 製フレームワーク (Flask, Django REST framework など) と比較すると、FastAPI は、パフォーマンス、開発効率、ドキュメント自動生成の点で優位性があります。特に、型ヒントを活用した開発は、コードの可読性、保守性、テスト容易性を向上させ、大規模なプロジェクトにおいても効果を発揮します。

2. 環境構築： FastAPI を始める準備

FastAPI を使い始めるには、まず開発環境を構築する必要があります。以下の手順に従って、必要なソフトウェアをインストールし、プロジェクトの初期設定を行いましょう。

2.1. Python のインストール

FastAPI は Python 3.6 以上を必要とします。Python がインストールされていない場合は、Python 公式サイト (https://www.python.org/downloads/) から最新版をダウンロードしてインストールしてください。

2.2. 仮想環境の作成

プロジェクトごとに独立した仮想環境を作成することをお勧めします。仮想環境を使用することで、プロジェクトごとに異なるバージョンのライブラリを使用でき、依存関係の競合を避けることができます。

以下のコマンドで仮想環境を作成します。

bash
python3 -m venv .venv

作成した仮想環境を有効化します。

bash
source .venv/bin/activate # Linux/macOS の場合
.venv\Scripts\activate # Windows の場合

2.3. FastAPI のインストール

仮想環境が有効になっている状態で、以下のコマンドで FastAPI をインストールします。

bash
pip install fastapi

2.4. Uvicorn のインストール

FastAPI アプリケーションを実行するためには、ASGI サーバーが必要です。ここでは、最もポピュラーな Uvicorn をインストールします。

bash
pip install uvicorn

2.5. エディタ/IDE の設定

FastAPI は型ヒントを積極的に活用するため、型ヒントをサポートするエディタ/IDE を使用することをお勧めします。Visual Studio Code (VS Code), PyCharm, Sublime Text など、多くのエディタ/IDE が Python の開発をサポートしており、型ヒントの補完、エラーチェック、リファクタリングなどの機能を提供します。

3. Hello World： 最初の FastAPI アプリケーション

環境構築が完了したら、最初の FastAPI アプリケーションを作成してみましょう。以下のコードを main.py という名前のファイルに保存してください。

“`python
from fastapi import FastAPI

app = FastAPI()

@app.get(“/”)
async def read_root():
return {“Hello”: “World”}
“`

このコードは、/ というエンドポイントに対して、{"Hello": "World"} という JSON データを返すシンプルな API を定義しています。

  • from fastapi import FastAPI: FastAPI ライブラリから FastAPI クラスをインポートします。
  • app = FastAPI(): FastAPI クラスのインスタンスを作成します。これが FastAPI アプリケーションの本体となります。
  • @app.get("/"): デコレータと呼ばれるもので、/ というパスに対する GET リクエストを処理する関数を登録します。
  • async def read_root(): 非同期関数を定義します。async キーワードを使用することで、高パフォーマンスな API を実現できます。
  • return {"Hello": "World"}: 関数が返す値を定義します。FastAPI は、Python の辞書型を自動的に JSON データに変換して返します。

4. アプリケーションの実行

作成した FastAPI アプリケーションを実行するには、以下のコマンドを実行します。

bash
uvicorn main:app --reload

  • uvicorn: Uvicorn ASGI サーバーを起動します。
  • main: FastAPI アプリケーションが定義されている Python ファイル名 (ここでは main.py) を指定します。
  • app: FastAPI アプリケーションのインスタンス名 (ここでは app) を指定します。
  • --reload: ファイルの変更を監視し、自動的にサーバーを再起動します。開発中に便利なオプションです。

コマンドを実行すると、以下のようなメッセージが表示されます。

INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [12345] using StatReload

これは、Uvicorn サーバーがポート 8000 で起動し、アプリケーションが実行されていることを意味します。

5. API のテスト

ブラウザまたは API クライアント (curl, Postman など) を使用して、http://127.0.0.1:8000/ にアクセスしてみてください。

ブラウザの場合、以下のような JSON データが表示されます。

json
{"Hello": "World"}

API クライアントの場合、以下のようなレスポンスが返ってきます。

“`
HTTP/1.1 200 OK
content-length: 17
content-type: application/json

{“Hello”: “World”}
“`

これで、最初の FastAPI アプリケーションが正常に動作することが確認できました。

6. パスパラメータ： 動的な API の構築

API は、固定されたデータを返すだけでなく、リクエストに応じて動的にデータを生成することも可能です。FastAPI では、パスパラメータを使用することで、URL に変数を含めることができます。

以下のコードを main.py に記述してください。

“`python
from fastapi import FastAPI

app = FastAPI()

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

このコードは、/items/{item_id} というエンドポイントに対して、item_id というパスパラメータを受け取り、その値を JSON データとして返す API を定義しています。

  • @app.get("/items/{item_id}"): /items/{item_id} というパスに対する GET リクエストを処理する関数を登録します。{item_id} は、パスパラメータとして認識されます。
  • async def read_item(item_id: int): item_id という引数を受け取る関数を定義します。item_id: int は、型ヒントと呼ばれるもので、item_id が整数型であることを明示的に指定しています。FastAPI は、この型ヒントに基づいて、自動的にリクエストされた item_id の値を整数型に変換します。

アプリケーションを再起動し、http://127.0.0.1:8000/items/123 にアクセスしてみてください。

以下のような JSON データが表示されます。

json
{"item_id": 123}

item_id の値を変更することで、返ってくるデータも動的に変化することが確認できます。

7. クエリパラメータ： リクエストのカスタマイズ

パスパラメータだけでなく、クエリパラメータを使用することで、リクエストをさらにカスタマイズすることができます。クエリパラメータは、URL の末尾に ? に続けて key=value の形式で記述します。

以下のコードを main.py に記述してください。

“`python
from fastapi import FastAPI

app = FastAPI()

@app.get(“/items/”)
async def read_item(item_id: int, q: str | None = None):
if q:
return {“item_id”: item_id, “q”: q}
return {“item_id”: item_id}
“`

このコードは、/items/ というエンドポイントに対して、item_id という必須のパスパラメータと、q というオプションのクエリパラメータを受け取り、それらの値を JSON データとして返す API を定義しています。

  • @app.get("/items/"): /items/ というパスに対する GET リクエストを処理する関数を登録します。
  • async def read_item(item_id: int, q: str | None = None): item_id と q という引数を受け取る関数を定義します。q: str | None = None は、q が文字列型または None 型であることを明示的に指定しており、デフォルト値を None に設定しています。これにより、q はオプションのパラメータとなります。

アプリケーションを再起動し、http://127.0.0.1:8000/items/?item_id=123&q=hello にアクセスしてみてください。

以下のような JSON データが表示されます。

json
{"item_id": 123, "q": "hello"}

q パラメータを省略した場合、以下のような JSON データが表示されます。

json
{"item_id": 123}

このように、クエリパラメータを使用することで、リクエストに応じて API の動作を柔軟に変更することができます。

8. リクエストボディ： データの送信

GET リクエストでは、URL に情報を付与してサーバーに送信しましたが、POST, PUT, DELETE などのリクエストでは、リクエストボディと呼ばれるデータ領域に情報を詰めて送信することが一般的です。FastAPI では、Pydantic というライブラリを使用して、リクエストボディの定義とバリデーションを簡単に行うことができます。

まず、Pydantic をインストールします。

bash
pip install pydantic

以下のコードを main.py に記述してください。

“`python
from fastapi import FastAPI
from pydantic import BaseModel

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

app = FastAPI()

@app.post(“/items/”)
async def create_item(item: Item):
return item
“`

このコードは、/items/ というエンドポイントに対して、POST リクエストを受け取り、リクエストボディに含まれる Item オブジェクトを JSON データとして返す API を定義しています。

  • from pydantic import BaseModel: Pydantic ライブラリから BaseModel クラスをインポートします。
  • class Item(BaseModel): Item というクラスを定義します。BaseModel を継承することで、Pydantic の機能を利用できます。
  • name: str: name という属性を定義します。str は、name が文字列型であることを明示的に指定しています。
  • description: str | None = None: description という属性を定義します。str | None = None は、description が文字列型または None 型であることを明示的に指定しており、デフォルト値を None に設定しています。
  • price: float: price という属性を定義します。float は、price が浮動小数点数型であることを明示的に指定しています。
  • tax: float | None = None: tax という属性を定義します。float | None = None は、tax が浮動小数点数型または None 型であることを明示的に指定しており、デフォルト値を None に設定しています。
  • @app.post("/items/"): /items/ というパスに対する POST リクエストを処理する関数を登録します。
  • async def create_item(item: Item): item という引数を受け取る関数を定義します。item: Item は、item が Item クラスのインスタンスであることを明示的に指定しています。FastAPI は、リクエストボディに含まれる JSON データを自動的に Item オブジェクトに変換します。

アプリケーションを再起動し、Postman などの API クライアントを使用して、以下の JSON データをリクエストボディに含めて http://127.0.0.1:8000/items/ に POST リクエストを送信してみてください。

json
{
"name": "Foo",
"description": "A very nice Item",
"price": 50.2,
"tax": 2.5
}

以下のような JSON データが返ってきます。

json
{
"name": "Foo",
"description": "A very nice Item",
"price": 50.2,
"tax": 2.5
}

FastAPI は、リクエストボディに含まれる JSON データを自動的に Item オブジェクトに変換し、そのオブジェクトを関数に渡していることが確認できます。

9. バリデーション： データの品質を保証

Pydantic を使用することで、リクエストボディのバリデーションを簡単に行うことができます。例えば、name 属性が必須であること、price 属性が正の数であることなどを定義することができます。

以下のコードを main.py に記述してください。

“`python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, validator

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

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

app = FastAPI()

@app.post(“/items/”)
async def create_item(item: Item):
return item
“`

このコードは、Item クラスにバリデーションルールを追加しています。

  • @validator('price'): price 属性に対するバリデーション関数を定義します。
  • def price_must_be_positive(cls, value): バリデーション関数を定義します。value は、price 属性の値です。
  • if value <= 0: price が 0 以下の場合、エラーを発生させます。
  • raise ValueError('price must be positive'): ValueError 例外を発生させます。この例外は、FastAPI によって自動的に HTTP エラーレスポンスに変換されます。
  • return value: バリデーションに成功した場合、値を返します。

アプリケーションを再起動し、Postman などの API クライアントを使用して、price を 0 以下の値に設定して POST リクエストを送信してみてください。

以下のようなエラーレスポンスが返ってきます。

json
{
"detail": [
{
"loc": [
"body",
"price"
],
"msg": "price must be positive",
"type": "value_error"
}
]
}

このように、Pydantic を使用することで、リクエストボディのバリデーションを簡単に行うことができ、API の信頼性を高めることができます。

10. エラーハンドリング： 予期せぬ事態への対処

API 開発において、エラーハンドリングは非常に重要な要素です。FastAPI では、例外処理機構を利用して、様々なエラーに対応することができます。

以下のコードを main.py に記述してください。

“`python
from fastapi import FastAPI, HTTPException

app = FastAPI()

items = {
“foo”: {“name”: “Foo”},
“bar”: {“name”: “Bar”}
}

@app.get(“/items/{item_id}”)
async def read_item(item_id: str):
if item_id not in items:
raise HTTPException(status_code=404, detail=”Item not found”)
return items[item_id]
“`

このコードは、/items/{item_id} というエンドポイントに対して、item_id に対応するアイテムが存在しない場合に、404 Not Found エラーを返す API を定義しています。

  • from fastapi import FastAPI, HTTPException: FastAPI ライブラリから FastAPI クラスと HTTPException クラスをインポートします。
  • raise HTTPException(status_code=404, detail="Item not found"): HTTPException 例外を発生させます。status_code は、HTTP ステータスコードを指定します。detail は、エラーメッセージを指定します。

アプリケーションを再起動し、http://127.0.0.1:8000/items/baz にアクセスしてみてください。

以下のようなエラーレスポンスが返ってきます。

json
{
"detail": "Item not found"
}

このように、HTTPException を使用することで、カスタムのエラーレスポンスを簡単に返すことができます。

11. セキュリティ： API の保護

API を安全に運用するためには、セキュリティ対策が不可欠です。FastAPI は、様々なセキュリティ機構をサポートしており、認証、認可、クロスサイトスクリプティング (XSS) 対策、クロスサイトリクエストフォージェリ (CSRF) 対策など、様々な脅威から API を保護することができます。

ここでは、最も基本的な認証方法である、API キー認証について説明します。

以下のコードを main.py に記述してください。

“`python
from fastapi import FastAPI, Depends, HTTPException
from fastapi.security import APIKeyHeader
from starlette.status import HTTP_403_FORBIDDEN

app = FastAPI()

API_KEY = “your_secret_api_key”
API_KEY_NAME = “X-API-Key”

api_key_header = APIKeyHeader(name=API_KEY_NAME, auto_error=False)

async def get_api_key(api_key_header: str = Depends(api_key_header)):
if api_key_header == API_KEY:
return api_key_header
else:
raise HTTPException(
status_code=HTTP_403_FORBIDDEN, detail=”Could not validate API key”
)

@app.get(“/items/”, dependencies=[Depends(get_api_key)])
async def read_items():
return [{“name”: “Foo”}, {“name”: “Bar”}]
“`

このコードは、/items/ というエンドポイントに対して、API キー認証を要求する API を定義しています。

  • from fastapi.security import APIKeyHeader: FastAPI ライブラリから APIKeyHeader クラスをインポートします。
  • API_KEY = "your_secret_api_key": API キーを設定します。本番環境では、安全な場所に保管し、ハードコードしないようにしてください。
  • API_KEY_NAME = "X-API-Key": API キーを送信するためのヘッダー名を指定します。
  • api_key_header = APIKeyHeader(name=API_KEY_NAME, auto_error=False): APIKeyHeader クラスのインスタンスを作成します。auto_error=False は、API キーが不正な場合に自動的にエラーレスポンスを返さないように設定します。
  • async def get_api_key(api_key_header: str = Depends(api_key_header)): API キーを検証する関数を定義します。Depends(api_key_header) は、api_key_header インスタンスを関数に注入します。
  • @app.get("/items/", dependencies=[Depends(get_api_key)]): /items/ というエンドポイントに対して、get_api_key 関数を依存関係として指定します。これにより、/items/ エンドポイントにアクセスするには、get_api_key 関数による認証を通過する必要があります。

アプリケーションを再起動し、Postman などの API クライアントを使用して、X-API-Key ヘッダーに正しい API キーを設定して http://127.0.0.1:8000/items/ にアクセスしてみてください。

以下のような JSON データが返ってきます。

json
[
{
"name": "Foo"
},
{
"name": "Bar"
}
]

X-API-Key ヘッダーを省略した場合、または不正な API キーを設定した場合、以下のようなエラーレスポンスが返ってきます。

json
{
"detail": "Could not validate API key"
}

このように、API キー認証を使用することで、API を不正なアクセスから保護することができます。

12. ドキュメント自動生成： API の可視化

FastAPI の大きな特徴の一つは、API ドキュメントを自動生成できることです。OpenAPI (Swagger UI) と ReDoc を標準でサポートしており、API の定義に基づいて、自動的にドキュメントを生成し、ブラウザで閲覧することができます。

アプリケーションを実行している状態で、http://127.0.0.1:8000/docs にアクセスしてみてください。

Swagger UI が表示され、定義した API のエンドポイント、パラメータ、リクエストボディ、レスポンスなどの情報が、インタラクティブな形式で表示されます。

また、http://127.0.0.1:8000/redoc にアクセスすると、ReDoc が表示され、Swagger UI とは異なる形式で API ドキュメントが表示されます。

API の定義を変更すると、ドキュメントも自動的に更新されるため、常に最新のドキュメントを維持することができます。

まとめ

本記事では、FastAPI を用いた API 開発の基礎を、ドキュメントを読み解きながら解説しました。FastAPI の基本的な概念、インストール方法、API の定義、リクエストの処理、データのバリデーション、セキュリティ対策、そしてドキュメントの自動生成まで、FastAPI を使い始めるための第一歩を、詳細なコード例と解説とともに提供しました。

FastAPI は、高速性、開発効率、型安全性、使いやすさ、標準ベース、Production Ready など、多くの利点を持つ優れた Web API フレームワークです。本記事で学んだ知識を基に、より複雑な API の開発に挑戦し、FastAPI の可能性を最大限に引き出してください。

さらに学習を進めるには、FastAPI 公式ドキュメント (https://fastapi.tiangolo.com/) を参照することをお勧めします。公式ドキュメントには、より詳細な情報や、高度な機能に関する解説が記載されています。

FastAPI を活用して、素晴らしい Web API を構築してください！

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール