REST APIの設計をClaudeに相談する

REST APIの設計は、チーム間の認識合わせや仕様の一貫性など、考慮すべきことが多い作業です。Claude Codeを使えば、エンドポイントの命名からエラーレスポンスの形式まで、対話しながら素早く設計を固められます。

エンドポイント設計をClaudeに相談する

まずはプロジェクトの概要をClaudeに伝えましょう。たとえばタスク管理アプリのAPIを設計したい場合、次のように入力します。

タスク管理アプリのREST APIを設計してください。
エンティティはUser・Project・Taskです。
CRUD操作が必要で、TaskはProjectに紐づきます。
RESTのベストプラクティスに従ったエンドポイント一覧をください。

するとClaudeはGET /projects/{projectId}/tasksのようなネストされたリソース設計や、PATCHとPUTの使い分けまで提案してくれます。「なぜこの設計か」も説明してくれるので、チームへの説明資料としても活用できます。

※REST API: Representational State Transfer の設計原則に基づくAPI。URLとHTTPメソッド（GET/POST/PUT/DELETE）でリソースを操作する。※エンドポイント: APIにアクセスするためのURL。例: `/api/users` や `/api/posts/123` など。※API: Application Programming Interface の略。外部サービスとプログラム間でデータをやりとりするための接続口。

レスポンス形式とOpenAPI仕様を生成する

エンドポイントが固まったら、レスポンスのJSON形式とOpenAPI仕様を一気に生成しましょう。

上記のエンドポイントについて、以下を生成してください。
1. 成功時・エラー時のレスポンスJSON例
2. OpenAPI 3.0形式のYAML定義
エラーレスポンスはRFC 7807（Problem Details）に準拠してください。

Claudeが出力したYAMLは、そのままSwagger UIやStoplightに貼り付けて確認できます。生成されたOpenAPI定義をファイルに保存するには次のコマンドを使いましょう。

# ClaudeのコードブロックをコピーしてYAMLファイルに保存
cat > openapi.yaml << 'EOF'
# ここにClaudeが生成したYAMLを貼り付ける
EOF

# Swagger CLIで仕様を検証する
npx @apidevtools/swagger-cli validate openapi.yaml

※CLI: Command Line Interface の略。ターミナル（黒い画面）からコマンドを入力して操作するインターフェース。

エラーハンドリングの設計を深掘りする

エラーレスポンスの設計は後回しにされがちですが、APIの使いやすさに直結します。Claudeに具体的なケースを挙げて相談しましょう。

以下のエラーケースのHTTPステータスコードとレスポンスボディを設計してください。
- 存在しないタスクへのアクセス
- 権限のないプロジェクトへの操作
- バリデーションエラー（複数フィールド）
- レートリミット超過

設計フェーズからClaudeを巻き込むことで、仕様の抜け漏れを早期に発見し、ドキュメントと実装を一致させやすくなります。ぜひ次のAPI設計から試してみてください。

※レートリミット: APIへのリクエスト回数に設けられた上限。超えるとエラーが返る。