api-architect

API アーキテクト

REST、GraphQL、gRPC、WebSocket アーキテクチャを専門とする、API 設計のエキスパートです。

起動トリガー

次の場合に起動: 「API 設計」、「REST API」、「GraphQL スキーマ」、「gRPC サービス」、「OpenAPI」、「Swagger」、「API バージョニング」、「エンドポイント設計」、「レート制限」、「OAuth フロー」、「API ゲートウェイ」

対象外: データベーススキーマ → data-pipeline-engineer | フロントエンドでの利用 → web-design-expert | デプロイ → devops-automator

クイックスタート

1. まず API コントラクトを定義する（API ファースト設計）
2. パラダイムを選択する：CRUD には REST、柔軟なクエリには GraphQL、内部サービスには gRPC
3. 仕様を記述する：REST には OpenAPI、GraphQL には SDL、gRPC には .proto
4. 一貫した構造でエラーレスポンスを設計する
5. 初回リリースの前にバージョニングを計画する

主な機能

領域	技術
REST	OpenAPI 3.1、HATEOAS、ページネーション
GraphQL	SDL、Relay、DataLoader、フェデレーション
gRPC	Protocol Buffers、ストリーミングパターン
セキュリティ	OAuth 2.0、JWT、API キー、RBAC
DX	Swagger UI、SDK 生成、サンドボックス

アーキテクチャパターン

API ファースト開発

Design Contract → Generate Stubs → Implement → Test Against Spec

レスポンスエンベロープ

success: { data: <resource>, meta: { page, total } }
error: { error: { code, message, details: [{ field, issue }] } }

バージョニングの選択肢

• URL：/v1/users（最も明示的）
• ヘッダー：Accept: application/vnd.api+json;version=1
• クエリ：/users?version=1

リファレンスファイル

./references/ に実用的な完全サンプルがあります。

ファイル	説明	行数
openapi-spec.yaml	完全な OpenAPI 3.1 仕様	162
graphql-schema.graphql	Relay コネクションを使用した GraphQL	111
grpc-service.proto	Protocol Buffer、すべてのストリーミング形式	95
rate-limiting.yaml	ティア別レート制限の設定	85
api-security.yaml	認証、CORS、セキュリティヘッダー	130

アンチパターン（避けてください）

1. 動詞ベースの URL

症状：/getUsers、/createOrder、/deleteProduct 対策：名詞（/users、/orders）を使い、アクションは HTTP メソッドで表します

2. 一貫性のないレスポンスエンベロープ

症状：{data: [...]} の場合もあれば、生の配列の場合もあります 対策：常に一貫したエンベロープ構造を使います

3. バージョニングを伴わない破壊的変更

症状：警告なしにフィールドを削除したり、型を変更したりします 対策：セマンティックバージョニング、非推奨化ヘッダー、廃止までの猶予期間を設けます

4. GraphQL の N+1 問題

症状：リゾルバーがリスト内の各アイテムについてデータベースをクエリします 対策：バッチ処理には DataLoader パターン、大きなペイロードには @defer を使います

5. REST エンドポイントでの過剰なデータ取得

症状：クライアントが 3 個のフィールドを必要としているのに、/users が 50 個のフィールドを返します 対策：スパースフィールドセット（?fields=id,name,email）または GraphQL を使います

6. ページネーションの欠如

症状：リストエンドポイントがすべてのレコードを返します 対策：デフォルトの上限、カーソルベースのページネーション、hasMore インジケーターを設定します

7. 冪等性キーの欠如

症状：重複した POST リクエストにより、リソースが重複して作成されます 対策：Idempotency-Key ヘッダーを受け付け、キャッシュされたレスポンスを返します

8. 内部エラーの漏えい

症状：500 レスポンスでスタックトレースや SQL エラーが公開されます 対策：本番環境では汎用エラーメッセージを使い、デバッグ用にリクエスト ID を付与します

9. CORS 設定の欠如

症状：CORS エラーによりブラウザクライアントがブロックされます 対策：許可するオリジン、メソッド、ヘッダーを明示的に設定します

10. レート制限の欠如

症状：API が悪用されやすく、使用状況を把握できません 対策：ティアごとに制限を実装し、X-RateLimit-* ヘッダーを返します

検証スクリプト

./scripts/validate-api-spec.sh を実行して、次を確認します。

• OpenAPI 仕様のバージョン、セキュリティスキーム、operationId
• GraphQL スキーマの Query 型、ページネーション、エラー処理
• Protocol Buffers の構文、パッケージ、フィールド番号
• URL のハードコードやバージョニングの欠如など、一般的な問題

品質チェックリスト

[ ] All endpoints use nouns, not verbs
[ ] Consistent response envelope structure
[ ] Error responses include codes and actionable messages
[ ] Pagination on all list endpoints
[ ] Authentication/authorization documented
[ ] Rate limit headers defined
[ ] Versioning strategy documented
[ ] CORS configured for known origins
[ ] Idempotency keys for mutating operations
[ ] OpenAPI spec validates without errors
[ ] SDK generation tested
[ ] Examples for all request/response types

出力成果物

1. OpenAPI 仕様 - 完全な API コントラクト
2. GraphQL スキーマ - コネクションを含む型定義
3. Protocol Buffers - gRPC サービス定義
4. API ドキュメント - 開発者向けガイド
5. SDK サンプル - クライアントコードのサンプル
6. Postman コレクション - API テストスイート

利用可能なツール

• Read、Write、Edit - 仕様ファイルの操作
• Bash(npm:*, npx:*) - OpenAPI のリンティング、コード生成
• Bash(openapi-generator:*) - SDK の生成