はじめに
「REST APIの設計原則がよくわからない」
「認証・バリデーション・エラーハンドリングを毎回ゼロから書くのが面倒」
「APIドキュメントを自動生成したい」
REST APIの実装には多くのボイラープレートが必要です。Claude Codeを使えば、設計から実装・テスト・ドキュメント生成まで一貫して効率化できます。
目次
- API設計をClaude Codeに相談する
- エンドポイントの実装
- バリデーションの実装
- 認証・認可の実装
- エラーハンドリングの統一
- OpenAPIドキュメントの自動生成
- APIテストの自動生成
- まとめ
1. API設計をClaude Codeに相談する
要件からAPI設計を生成する
> 以下の要件でREST APIを設計してください。
システム：タスク管理アプリ
必要な機能：
- ユーザー登録・ログイン
- タスクのCRUD操作
- タスクのカテゴリ管理
- タスクの検索・フィルタリング
以下を含むAPI設計書を作成してください：
- エンドポイント一覧（メソッド・パス・説明）
- リクエスト/レスポンスのJSON形式
- ステータスコードの定義
- 認証方式（JWTを想定）
- ページネーション方式既存APIの設計レビュー
> 現在のAPIエンドポイントを分析して、
RESTの原則に反している箇所を指摘してください。
チェック観点：
- リソース指向の命名（動詞ではなく名詞）
- HTTPメソッドの適切な使用
- ステータスコードの適切な使用
- 一貫性のない命名規則
- バージョニング戦略2. エンドポイントの実装
FastAPIでのAPI実装
> 以下の設計でFastAPIのAPIを実装してください。
エンドポイント：
- GET /tasks - タスク一覧（ページネーション対応）
- POST /tasks - タスク作成
- GET /tasks/{id} - タスク詳細
- PUT /tasks/{id} - タスク更新
- DELETE /tasks/{id} - タスク削除
使用技術：
- FastAPI + Pydantic v2
- SQLAlchemy 2.0 + asyncpg（非同期）
- Alembicでマイグレーション管理
ディレクトリ構成も提案してください。Expressでの実装（Node.js）
> TypeScriptを使ったExpress APIを実装してください。
要件：
- ルーターを機能単位でモジュール化
- Zodによるバリデーション
- Prismaによるデータベースアクセス
- エラーハンドリングのミドルウェア
- ロギングミドルウェア（morgan）3. バリデーションの実装
入力バリデーションの追加
> このAPIエンドポイントに適切なバリデーションを追加してください。
バリデーションルール：
- title：必須・最大200文字・HTMLタグ不可
- due_date：ISO 8601形式・過去日付不可
- priority：1〜5の整数のみ
- tags：配列・最大10件・各タグは最大30文字
バリデーションエラーは具体的なメッセージでレスポンスに含めてください。カスタムバリデーターの実装
> 以下のカスタムバリデーションを実装してください：
- メールアドレスが既に登録済みでないか確認する非同期バリデーター
- 日付の範囲チェック（開始日 < 終了日）
- 相互依存フィールドのバリデーション4. 認証・認可の実装
JWT認証の実装
> JWT認証をこのAPIに実装してください。
要件：
- アクセストークン（有効期限15分）
- リフレッシュトークン（有効期限7日）
- リフレッシュトークンのローテーション
- ブラックリストによるトークン無効化
- HTTPS専用のSecure Cookie設定
セキュリティのベストプラクティスに従ってください。ロールベースアクセス制御（RBAC）
> このAPIにロールベースのアクセス制御を追加してください。
ロール定義：
- admin：すべての操作が可能
- manager：チームのリソースのみ操作可能
- user：自分のリソースのみ操作可能
デコレーターまたはミドルウェアで実装してください。
各エンドポイントに必要な権限をコメントで明記してください。5. エラーハンドリングの統一
グローバルエラーハンドラーの実装
> APIのエラーレスポンスを統一してください。
統一フォーマット：
{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "指定されたタスクが見つかりません",
"details": {...},
"request_id": "uuid"
}
}
対応するエラー：
- バリデーションエラー（422）
- 認証エラー（401）
- 認可エラー（403）
- リソース未発見（404）
- レートリミット（429）
- サーバーエラー（500）
エラーコードの一覧表もドキュメント化してください。6. OpenAPIドキュメントの自動生成
Swagger UIの設定
> このAPIのOpenAPI 3.0ドキュメントを自動生成する設定を行ってください。
要件：
- /docs でSwagger UIにアクセスできる
- /redoc でReDocにアクセスできる
- /openapi.json でOpenAPIスキーマを取得できる
- すべてのエンドポイントに説明・例・レスポンス定義を追加
- 認証方法をドキュメントに記載APIドキュメントの品質チェック
> 現在のOpenAPIドキュメントを分析して、
ドキュメントが不足・不正確な箇所を指摘して修正してください。
チェック項目：
- すべてのエンドポイントに説明があるか
- リクエスト例が提供されているか
- エラーレスポンスが定義されているか
- deprecated（非推奨）なエンドポイントが適切にマークされているか7. APIテストの自動生成
pytestまたはJestでのAPIテスト
> このAPIの統合テストを作成してください。
使用ツール：pytest + httpx（FastAPIの場合）
テストシナリオ：
- 正常系：各エンドポイントの通常操作
- 認証エラー：トークンなし・無効なトークン
- バリデーションエラー：不正な入力値
- 権限エラー：権限のないユーザーによるアクセス
- 404エラー：存在しないリソースへのアクセス
テスト用データベースはSQLiteを使ってCI環境でも動くようにしてください。コントラクトテストの設定
> PactまたはDreddを使ってAPIのコントラクトテストを設定してください。
フロントエンドとバックエンドのAPI仕様の乖離を自動検出できるようにしてください。8. まとめ
Claude CodeでのAPI開発の効率化ポイント：
- 要件からエンドポイント設計を自動生成できる
- バリデーション・認証・エラーハンドリングのボイラープレートを自動作成
- OpenAPIドキュメントを自動生成・検証できる
- 統合テストをエンドポイントから自動生成できる
フレームワーク別推奨：
- Python系：FastAPI + Pydantic v2（型安全でドキュメント自動生成）
- Node.js系：Express + TypeScript + Zod
次回の第23回：データベースのマイグレーションでは、スキーマ変更を安全に管理する方法を解説します。
よくある質問（FAQ）
Q. GraphQLのAPI設計にも対応できますか？
A. はい。「FastAPIでGraphQLのAPIを実装してください。Strawberryを使ってください」のように指定することで対応できます。スキーマファーストの設計も相談できます。
Q. APIのバージョニングはどう設計すればいいですか？
A. URLパス（/api/v1/）・ヘッダー（Accept-Version）・クエリパラメータの3方式があります。Claude Codeに「このAPIにバージョニングを追加してください。ユースケースを教えてから最適な方式を提案してください」と相談することをお勧めします。
この記事はClaude Code入門シリーズ（第3部）の第22回です。← 第21回：Python開発 ｜ 第23回：DBマイグレーション →
ご質問はお問い合わせページからお気軽にどうぞ。
