🔖

# 3.1 API 設計の実際（Django REST Framework 編）

に公開
Django
tech

前回の記事では Django REST Framework（DRF）の基本 を紹介した。
CRUD API をすぐに作れるのが DRF の強みだが、業務システムで長期運用するには 設計の工夫 が欠かせない。

この記事では、実際の API 設計で気をつけているポイントを総論的に整理する。
また、AI に設計や実装を支援させるときの 指示例（プロンプト例） も併せて紹介する。

1. Serializer の設計方針

DRF では ModelSerializer を使うとモデルをそのまま JSON に変換できる。
ただし業務システムではケースごとに Serializer を使い分けることが多い。

よくあるパターン

  • 一覧用と詳細用を分ける
  • 入力用と出力用を分ける
  • ネスト構造の扱いを場面で決める

💡 AI 指示例

この Django モデルをもとに、一覧用と詳細用の Serializer をそれぞれ作ってください。
出力用では関連モデルを展開、入力用では関連 id のみ受け取る形にしてください。

2. バージョン管理

API は一度公開すると簡単には変えられない。
破壊的変更を避けるため、最初からバージョン管理を意識する。

  • URL で明示する: /api/v1/orders/
  • 将来 /api/v2/ を並行稼働
  • 廃止予定 API には warning を出す

💡 AI 指示例

既存の API ドキュメントを v1 として整理し、将来 v2 を追加できる構成に変更してください。
非推奨 API には deprecation 警告を付けてください。

3. エラーハンドリング

統一されたエラーレスポンスを返すことが重要。

例: バリデーションエラー

{
  "error": "ValidationError",
  "message": {
    "customer_name": ["このフィールドは必須です。"]
  }
}

例: 認可エラー

{
  "error": "PermissionDenied",
  "message": "この操作を実行する権限がありません。"
}

💡 AI 指示例

Django REST Framework でバリデーションエラー・認証エラー・認可エラーを
すべて統一形式で返す実装例を提示してください。
レスポンス JSON は error と message を含む形式にしてください。

4. フィルタリングと検索

一覧 API に検索条件をつけたいニーズは多い。

  • django-filter を活用
  • ページネーションを標準化 (limit/offset or cursor)

💡 AI 指示例

この Order モデルに対して、customer_name と date_from/date_to で検索できる API を作ってください。
django-filter を利用し、レスポンスには count / next / previous / results を含めてください。

5. パフォーマンスと N+1 対策

Serializer で関連モデルを展開するときに N+1 が発生しがち。

  • select_related / prefetch_related の活用
  • 不要な関連展開を避ける
  • 重い処理はキャッシュや非同期ジョブへ

💡 AI 指示例

この ViewSet で発生している N+1 クエリを解消するようにコードを修正してください。
select_related と prefetch_related を適切に追加してください。

6. レスポンス設計のベストプラクティス

  • id は必ず含める
  • 一覧と詳細で返す項目を変える
  • フロントで使いやすい形にする（例: 金額は数値と文字列両方）
{
  "id": 1,
  "customer_name": "株式会社テスト",
  "total_amount": 50000,
  "total_amount_display": "¥50,000"
}

💡 AI 指示例

この API のレスポンスに total_amount_display を追加してください。
数値 total_amount を通貨フォーマットした文字列を返すようにしてください。

まとめ

CRUD を自動生成できる DRF でも、実際の業務システムで長期運用するには以下が重要になる。

  • Serializer の分割と設計方針
  • バージョン管理
  • エラーハンドリングの統一
  • フィルタリング・検索の設計
  • パフォーマンスと N+1 対策
  • フロントで扱いやすいレスポンス設計

AI を活用する際に大事なのは、
「最初から完璧に指示すること」ではなく「必要に応じて段階的に指示すること」。

まずはシンプルに依頼し、出力が想定と異なれば
「一覧用と詳細用を分けて」「N+1 を避けて」「レスポンスはこの形式で」
と追加指示する。

このように 段階的に明確化していくプロセス の方が効率的であり、
人間が考えた設計方針を AI に反映させやすい。

Discussion