Claude CodeでREST API設計を爆速で仕上げるテクニック

REST APIの設計は、エンドポイント命名、リクエスト/レスポンス設計、バリデーション、エラーハンドリング、ドキュメントと考えることが多いです。Claude Code をAPI設計のパートナーにすれば、設計から実装まで一気通貫で進められます。

1. エンドポイント設計を相談する

最初の設計段階から Claude Code に壁打ちできます。

claude -p "
ECサイトのREST APIを設計してください。

リソース:
- ユーザー（登録、ログイン、プロフィール）
- 商品（一覧、詳細、検索）
- カート（追加、削除、取得）
- 注文（作成、一覧、詳細、キャンセル）

RESTful な命名規則に従って、
全エンドポイントをHTTPメソッド付きでリストアップしてください。
認証が必要なエンドポイントにはマークを付けてください。
"

数秒で、20〜30のエンドポイント設計が返ってきます。命名の一貫性やHTTPメソッドの使い分けもRESTのベストプラクティスに沿ってくれます。

2. OpenAPI定義を自動生成

設計が決まったら、OpenAPI（Swagger）定義を一発で生成します。

claude -p "
先ほど設計したエンドポイントの OpenAPI 3.1 定義を
YAML で作成してください。

各エンドポイントに:
- リクエストボディのスキーマ
- レスポンスのスキーマ（成功 + エラー）
- パスパラメータ、クエリパラメータ
- 認証（Bearer Token）
- 説明文

出力先: docs/openapi.yaml
"

手で書くと半日かかるOpenAPI定義が、5分で完成します。

3. バリデーションを自動実装

Zodを使ったバリデーションスキーマも自動生成できます。

claude -p "
docs/openapi.yaml を読んで、各エンドポイントの
リクエストバリデーションを Zod で実装してください。

出力先: src/validators/

含めてほしいもの:
- パスパラメータのバリデーション
- クエリパラメータのバリデーション
- リクエストボディのバリデーション
- カスタムエラーメッセージ（日本語）
"

OpenAPI定義とバリデーションコードの二重管理を防げます。詳しくは Zod バリデーション活用 も参照。

4. エラーハンドリングを統一する

APIのエラーレスポンスを統一的に設計します。

claude -p "
このAPIプロジェクトに統一的なエラーハンドリングを実装してください。

要件:
- RFC 7807 (Problem Details) 形式
- HTTPステータスコードと対応するエラータイプ
- バリデーションエラーは各フィールドの詳細を含む
- 本番ではスタックトレースを隠す
- エラーログは構造化ログ（JSON）で出力

src/middleware/error-handler.ts に実装してください。
"

5. テストを自動生成

APIエンドポイントのテストも一括生成できます。

claude -p "
src/routes/ 配下の全エンドポイントに対して、
統合テストを Vitest + Supertest で作成してください。

各エンドポイントに:
- 正常系テスト（200/201）
- バリデーションエラーテスト（400）
- 認証エラーテスト（401）
- 存在しないリソーステスト（404）

テストデータはファクトリーパターンで管理してください。
出力先: tests/api/
"

4つのパターン × エンドポイント数のテストが自動生成されます。テスト戦略ガイド も参考に。

6. ドキュメントを自動更新

コードを変更したら、ドキュメントも自動で追従させます。

claude -p "
src/routes/ のコードを読んで、
docs/openapi.yaml を最新の状態に更新してください。

新しいエンドポイントが追加されていたら定義を追加し、
削除されたものがあれば定義から除去してください。
"

コードとドキュメントの乖離を防げます。

7. レート制限とキャッシュ戦略

パフォーマンスに関わる設計も相談できます。

claude -p "
このAPIに以下を実装してください:

1. レート制限（sliding window方式、Redis使用）
   - 未認証: 60リクエスト/分
   - 認証済み: 300リクエスト/分

2. キャッシュ戦略（Cache-Control ヘッダー）
   - 商品一覧: 5分キャッシュ
   - 商品詳細: 1分キャッシュ
   - ユーザー情報: no-cache
   - 静的アセット: 1日キャッシュ
"

レート制限の実装 と キャッシュ戦略 も参考になります。

ハマりどころ

N+1クエリに注意

Claude Codeが生成するAPIコードは、時々N+1クエリを含むことがあります。「このエンドポイントのSQLクエリを最適化して」と追加で指示すると修正してくれます。

認証と認可を分離する

「認証（誰か）」と「認可（何ができるか）」を混同しないよう、CLAUDE.md に方針を明記しておきましょう。

バージョニングを忘れずに

APIのバージョニング（/api/v1/）は最初から入れておくのがベスト。後から追加するのは大変です。APIバージョニング戦略 を参照。

まとめ

• エンドポイント設計を壁打ちして品質を上げる
• OpenAPI定義を自動生成して手作業をゼロに
• Zodバリデーションをスキーマから自動実装
• エラーハンドリングをRFC 7807で統一
• テストを4パターン×全エンドポイントで自動生成
• ドキュメントとコードの同期を自動化
• レート制限・キャッシュ戦略も相談できる

Claude CodeをAPI設計のパートナーにすると、設計品質と開発速度の両方が劇的に上がります。公式ドキュメントは Anthropic Claude Code を参照。