ノートAPIの構築

ここから、ノートアプリケーションのCRUD APIを構築していきます。エンドポイントを一つずつ追加しながら、コードの記述、解説、動作確認を繰り返して進めます。

1. ベースコードの作成

まずmain.pyを作成します。

note-api/
├── .env
├── models.py
├── database.py
├── setup_db.py
└── main.py  ← このファイルを作成

作成したファイルに以下の内容を記述して保存します。

from contextlib import asynccontextmanager

from fastapi import FastAPI

from database import create_db_and_tables
from routers.notes import router as notes_router

@asynccontextmanager
async def lifespan(app: FastAPI):
    create_db_and_tables()
    yield

app = FastAPI(lifespan=lifespan)

app.include_router(notes_router)

@app.get("/health")
def health_check():
    return {"status": "healthy"}

if __name__ == "__main__":
    import uvicorn

    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

コードを解説します。

from routers.notes import router as notes_router

routers/notes.pyからルータをインポートしています。as notes_routerで別名を付けることで、どのルータかが分かりやすくなります。

@asynccontextmanager
async def lifespan(app: FastAPI):
    create_db_and_tables()
    yield

lifespanは、FastAPIアプリケーションの起動時に実行される処理を定義する仕組みです。yieldの前に書いた処理(create_db_and_tables())はアプリケーションの起動時に1回だけ実行されます。これにより、サーバ起動時にテーブルが存在しなければ自動的に作成されます。

app = FastAPI(lifespan=lifespan)

app.include_router(notes_router)

FastAPIのインスタンスを作成し、app.include_router()でrouters/notes.pyに定義したエンドポイントをアプリケーションに登録しています。これにより、routers/notes.pyで定義した全てのエンドポイントがmain.pyのアプリケーションに組み込まれます。

@app.get("/health")
def health_check():
    return {"status": "healthy"}

ヘルスチェック用のエンドポイントです。アプリケーション全体の状態を確認するものなので、main.pyに直接定義しています。

if __name__ == "__main__":
    import uvicorn

    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

python main.pyで直接実行した場合に、uvicornサーバを起動する処理です。reload=Trueを指定すると、コードを変更するたびにサーバが自動的に再起動されます。

📝 APIRouterとは
FastAPIのAPIRouterは、エンドポイントをグループ化して別ファイルに分離するための仕組みです。main.pyにすべてのエンドポイントを書くとファイルが肥大化するため、機能ごとにルータファイルを分けてapp.include_router()で登録するのがFastAPIの推奨パターンです。詳しくはFastAPI公式ドキュメントのBigger Applications - Multiple Filesに記載があります。

2. ルータファイルの作成

次に、ノートAPIのエンドポイントを定義するrouters/notes.pyを作成します。まずroutersフォルダを作成し、その中にnotes.pyを作成してください。

note-api/
├── .env
├── models.py
├── database.py
├── setup_db.py
├── main.py
└── routers/           ← このフォルダを作成
    └── notes.py       ← このファイルを作成

作成したファイルに以下の内容を記述して保存します。

from fastapi import APIRouter, Depends, HTTPException
from sqlmodel import Session, select

from database import get_session
from models import Note, NoteCreate

router = APIRouter()

# ---- エンドポイント(この下に追加していきます) ----

コードを解説します。

from fastapi import APIRouter, Depends, HTTPException

APIRouterをインポートしています。APIRouterはFastAPIと同じようにエンドポイントを定義できますが、単体ではアプリケーションとして動作しません。main.pyのapp.include_router()で登録することで有効になります。

router = APIRouter()

APIRouterのインスタンスを作成しています。このrouterに対してエンドポイントを定義していきます。main.pyでは@app.get()のようにアプリケーションに直接定義していましたが、ルータファイルでは@router.get()のようにルータに対して定義します。

この時点でサーバを起動しておきます。--reloadオプションにより、コードを変更するたびにサーバが自動的に再起動されるため、エンドポイントを追加するたびにサーバを手動で再起動する必要はありません。

Windowsの場合:

python main.py

Macの場合:

python3 main.py

以下のような出力が表示されれば、サーバが正常に起動しています。

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [xxxxx] using StatReload
INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

動作確認は、サーバとは別のターミナルを開いて行います。Visual Studio Codeでは、ターミナルパネル右上の「+」ボタンをクリックすると、新しいターミナルを追加できます。サーバを起動したターミナルはそのまま残し、新しいターミナルでcurlコマンドを実行してください。

3. ノート作成(POST /notes)

最初に、ノートを作成するエンドポイントを実装します。routers/notes.pyの# ---- エンドポイントのコメントの下に、以下のコードを追加します。

@router.post("/notes", status_code=201)
def create_note(note: NoteCreate, session: Session = Depends(get_session)):
    db_note = Note(title=note.title, content=note.content)
    session.add(db_note)
    session.commit()
    session.refresh(db_note)
    return db_note

追加したコードを解説します。

@router.post("/notes", status_code=201)
def create_note(note: NoteCreate, session: Session = Depends(get_session)):

@router.post("/notes", status_code=201)で、POST /notesにリクエストが来たときに実行されるエンドポイントを定義しています。status_code=201は、リソースの作成が成功したことを示すHTTPステータスコードです。引数のnote: NoteCreateにより、リクエストボディのJSONデータがNoteCreateモデルに自動変換されます。session: Session = Depends(get_session)で、データベースセッションが自動的に注入されます。

db_note = Note(title=note.title, content=note.content)
session.add(db_note)
session.commit()

Note(title=..., content=...)でテーブルモデルのインスタンスを作成し、session.add()でセッションに追加、session.commit()でデータベースに保存しています。

session.refresh(db_note)
return db_note

session.refresh(db_note)は、データベースが自動付与したidやcreated_atなどの値をインスタンスに反映します。これにより、レスポンスにこれらの値を含めることができます。

3.1 動作確認

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

curl -X POST http://localhost:8000/notes \
  -H "Content-Type: application/json" \
  -d '{"title": "新しいノート", "content": "curlコマンドでノートを作成しました。"}'

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

{"title":"新しいノート","content":"curlコマンドでノートを作成しました。","id":3,"created_at":"2025-01-01T10:00:00","updated_at":"2025-01-01T10:00:00"}

新しいノートがid: 3で作成されました。created_atやupdated_atも自動的に設定されていることが確認できます。

💡 ポイント
setup_db.pyでテストデータを2件挿入しているため、新しく作成されたノートのIDは3になります。created_atとupdated_atの値は実行した日時によって異なります。

4. ノート一覧取得(GET /notes)

次に、ノートの一覧を取得するエンドポイントを追加します。先ほど追加したcreate_note関数の下に、以下のコードを追加します。

@router.get("/notes")
def get_notes(session: Session = Depends(get_session)):
    notes = session.exec(select(Note).order_by(Note.id.desc())).all()
    return notes

追加したコードを解説します。

notes = session.exec(select(Note).order_by(Note.id.desc())).all()
return notes

select(Note).order_by(Note.id.desc())で、全ノートをIDの降順(新しい順)で取得しています。.all()で全件をリストとして取得し、FastAPIが自動的にJSON形式に変換してレスポンスを返します。

4.1 動作確認

curlコマンドで動作を確認します。

curl http://localhost:8000/notes

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

[{"title":"新しいノート","content":"curlコマンドでノートを作成しました。","id":3,"created_at":"2025-01-01T10:00:00","updated_at":"2025-01-01T10:00:00"},{"title":"2番目のノート","content":"FastAPIとSQLModelの連携を学んでいます。","id":2,"created_at":"2025-01-01T10:00:00","updated_at":"2025-01-01T10:00:00"},{"title":"最初のノート","content":"これはテスト用の最初のノートです。","id":1,"created_at":"2025-01-01T10:00:00","updated_at":"2025-01-01T10:00:00"}]

テストデータの2件と、先ほど作成したノートの計3件が、新しい順に返されています。

5. ノート詳細取得(GET /notes/{note_id})

特定のノートを1件取得するエンドポイントを追加します。

@router.get("/notes/{note_id}")
def get_note(note_id: int, session: Session = Depends(get_session)):
    note = session.get(Note, note_id)
    if not note:
        raise HTTPException(status_code=404, detail="ノートが見つかりません")
    return note

追加したコードを解説します。

note = session.get(Note, note_id)

session.get(Note, note_id)で、主キー(ID)を指定してノートを1件取得します。ノートが存在しない場合はNoneが返されます。

if not note:
    raise HTTPException(status_code=404, detail="ノートが見つかりません")
return note

ノートが存在しない場合はHTTPExceptionで404エラーを返します。存在する場合はそのままnoteを返します。

5.1 動作確認

IDが1のノートを取得します。

curl http://localhost:8000/notes/1

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

{"title":"最初のノート","content":"これはテスト用の最初のノートです。","id":1,"created_at":"2025-01-01T10:00:00","updated_at":"2025-01-01T10:00:00"}

存在しないIDを指定した場合も確認してみましょう。

curl http://localhost:8000/notes/999

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

{"detail":"ノートが見つかりません"}

HTTPExceptionにより、404 Not Foundのステータスコードとエラーメッセージが返されています。

6. ノート更新(PUT /notes/{note_id})

ノートを更新するエンドポイントを追加します。

from models import NoteCreate, NoteUpdate, Note

ファイルの先頭にあるimport文に、NoteUpdateを追加します。

@router.put("/notes/{note_id}")
def update_note(
    note_id: int, note_data: NoteUpdate, session: Session = Depends(get_session)
):
    note = session.get(Note, note_id)
    if not note:
        raise HTTPException(status_code=404, detail="ノートが見つかりません")
    if note_data.title is not None:
        note.title = note_data.title
    if note_data.content is not None:
        note.content = note_data.content
    session.add(note)
    session.commit()
    session.refresh(note)
    return note

追加したコードを解説します。

note = session.get(Note, note_id)
if not note:
    raise HTTPException(status_code=404, detail="ノートが見つかりません")

ノート詳細取得と同様に、session.get()で対象のノートを取得し、存在しない場合は404エラーを返します。

if note_data.title is not None:
    note.title = note_data.title
if note_data.content is not None:
    note.content = note_data.content

NoteUpdateのフィールドはOptionalのため、クライアントが送信しなかったフィールドはNoneになります。is not Noneで判定し、値が送られたフィールドのみ更新しています。

ここでif note_data.title:ではなくif note_data.title is not None:と書いているのがポイントです。Pythonでは空文字""や数値の0はif value:の条件でfalse(偽)と判定されるため、if note_data.title:と書くと空文字をセットしたい場合にスキップされてしまいます。is not Noneで判定することで、「値が送られたかどうか」を正しく判定できます。

session.add(note)
session.commit()
session.refresh(note)
return note

前の章で学んだとおり、属性を変更してからsession.add()とsession.commit()で変更を確定させます。session.refresh()でupdated_atの更新値をインスタンスに反映しています。

💡 ポイント
HTTPメソッドにはPUTのほかにPATCHというメソッドもあります。PUTは「リソース全体の置き換え」を意味し、すべてのフィールドを送信するのが基本です。一方PATCHは「部分更新」を意味し、変更したいフィールドだけを送信します。今回の実装はNoteUpdate(全フィールドOptional)を使った部分更新の挙動なので、厳密にはPATCHが適切です。PUTを使う場合は全フィールドを必須にして全体を置き換える設計にします。実際にはPATCHを使うケースが多いですが、今回はHTTPメソッドの違いよりも更新処理のロジックを学ぶことを優先し、PUTで実装しています。

6.1 動作確認

先ほど作成したid: 3のノートを更新します。

curl -X PUT http://localhost:8000/notes/3 \
  -H "Content-Type: application/json" \
  -d '{"title": "更新したノート", "content": "内容を更新しました。"}'

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

{"title":"更新したノート","content":"内容を更新しました。","id":3,"created_at":"2025-01-01T10:00:00","updated_at":"2025-01-01T11:00:00"}

titleとcontentが更新され、updated_atが更新日時に変わっていることが確認できます。created_atは変わっていません。

詳細取得APIで、更新内容が反映されていることを確認してみましょう。

curl http://localhost:8000/notes/3

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

{"title":"更新したノート","content":"内容を更新しました。","id":3,"created_at":"2025-01-01T10:00:00","updated_at":"2025-01-01T11:00:00"}

先ほど更新したtitleとcontentが正しく保存されていることが確認できます。

7. ノート削除(DELETE /notes/{note_id})

ノートを削除するエンドポイントを追加します。

@router.delete("/notes/{note_id}")
def delete_note(note_id: int, session: Session = Depends(get_session)):
    note = session.get(Note, note_id)
    if not note:
        raise HTTPException(status_code=404, detail="ノートが見つかりません")
    session.delete(note)
    session.commit()
    return {"message": "ノートを削除しました"}

追加したコードを解説します。

note = session.get(Note, note_id)
if not note:
    raise HTTPException(status_code=404, detail="ノートが見つかりません")

ノート詳細取得と同様に、session.get()で対象のノートを取得し、存在しない場合は404エラーを返します。

session.delete(note)
session.commit()
return {"message": "ノートを削除しました"}

session.delete()でセッションから削除対象として登録し、session.commit()で削除を確定させます。削除が完了したら、メッセージを返します。

💡 ポイント
DELETEのレスポンスとして、今回はメッセージを含む200 OKを返していますが、REST APIの慣例ではレスポンスボディを返さない204 No Contentを使うことも一般的です。204を使う場合はreturn文を省略し、@router.delete("/notes/{note_id}", status_code=204)のようにステータスコードを指定します。

7.1 動作確認

id: 3のノートを削除します。

curl -X DELETE http://localhost:8000/notes/3

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

{"message":"ノートを削除しました"}

削除されたことを一覧取得で確認します。

curl http://localhost:8000/notes

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

[{"title":"2番目のノート","content":"FastAPIとSQLModelの連携を学んでいます。","id":2,"created_at":"2025-01-01T10:00:00","updated_at":"2025-01-01T10:00:00"},{"title":"最初のノート","content":"これはテスト用の最初のノートです。","id":1,"created_at":"2025-01-01T10:00:00","updated_at":"2025-01-01T10:00:00"}]

id: 3のノートが一覧から消えていることが確認できます。

8. ヘルスチェック(GET /health)

ヘルスチェック用のエンドポイントは、すでにmain.pyに定義済みです。アプリケーションが正常に動作しているかを確認するためのエンドポイントで、ロードバランサや監視ツールが定期的にこのエンドポイントにリクエストを送信し、アプリケーションの状態を監視します。ノートの操作とは異なりアプリケーション全体に関わるものなので、routers/notes.pyではなくmain.pyに配置しています。

8.1 動作確認

curlコマンドで動作を確認します。

curl http://localhost:8000/health

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

{"status":"healthy"}

9. バリデーションエラーの確認

ここまでの実装で、NoteCreateモデルによるバリデーションも自動的に機能しています。必須フィールドであるtitleを省略した場合の動作を確認してみましょう。

curl -X POST http://localhost:8000/notes \
  -H "Content-Type: application/json" \
  -d '{"content": "タイトルなし"}'

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

{"detail":[{"type":"missing","loc":["body","title"],"msg":"Field required","input":{"content":"タイトルなし"}}]}

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

💡 ポイント
全てのエンドポイントは、ブラウザでhttp://localhost:8000/docsにアクセスしてSwagger UIからもテストできます。特にPOSTやPUTのリクエストは、Swagger UIの「Try it out」ボタンから簡単に実行できるため、curlコマンドに不慣れな場合はこちらも活用してください。

動作確認が完了したら、ターミナルでCtrl + Cを押してサーバを停止してください。