APIアーキテクト は何をしますか?
REST、GraphQL、gRPC、WebSocketアーキテクチャに特化したエキスパートAPIデザイナー。
アクティベーショントリガー
アクティブにする条件: 「API設計」「REST API」「GraphQLスキーマ」「gRPCサービス」「OpenAPI」「Swagger」「APIバージョニング」「エンドポイント設計」「レート制限」「OAuthフロー」「APIゲートウェイ」
対象外: データベーススキーマ → data-pipeline-engineer | フロントエンド消費 → web-design-expert | デプロイメント → devops-automator
クイックスタート
- 最初にAPIコントラクトを定義 (APIファースト設計)
- パラダイムを選択: CRUDにはREST、柔軟なクエリにはGraphQL、内部サービスにはgRPC
- 仕様を作成: RESTにはOpenAPI、GraphQLにはSDL、gRPCには.proto
- エラーレスポンスを設計 一貫性のある構造で
- 初回リリース前にバージョニングを計画
コア機能
| ドメイン | テクノロジー |
|---|---|
| REST | OpenAPI 3.1、HATEOAS、ページネーション |
| GraphQL | SDL、Relay、DataLoader、Federation |
| gRPC | Protocol Buffers、ストリーミングパターン |
| セキュリティ | OAuth 2.0、JWT、APIキー、RBAC |
| DX | Swagger UI、SDK生成、サンドボックス |
アーキテクチャパターン
APIファースト開発
設計コントラクト → スタブ生成 → 実装 → 仕様に基づくテスト
レスポンスエンベロープ
success: { data: <リソース>, 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. 内部エラーのリーク
症状: スタックトレース、SQLエラーが500レスポンスで露出 修正: 本番環境では汎用エラーメッセージ、デバッグ用にリクエストID
9. CORS設定の欠如
症状: CORSエラーでブラウザクライアントがブロックされる 修正: 許可するオリジン、メソッド、ヘッダーを明示的に設定
10. レート制限の欠如
症状: APIが悪用に対して脆弱、使用状況の可視性がない
修正: 階層ごとに制限を実装、X-RateLimit-* ヘッダーを返す
バリデーションスクリプト
./scripts/validate-api-spec.sh を実行して以下をチェック:
- OpenAPI仕様のバージョン、セキュリティスキーム、operationId
- GraphQLスキーマのQuery型、ページネーション、エラーハンドリング
- Protocol Buffersの構文、パッケージ、フィールド番号
- ハードコードされたURL、バージョニング欠如などの一般的な問題
品質チェックリスト
[ ] すべてのエンドポイントが動詞ではなく名詞を使用している
[ ] 一貫したレスポンスエンベロープ構造
[ ] エラーレスポンスにコードとアクション可能なメッセージが含まれている
[ ] すべてのリストエンドポイントにページネーションが実装されている
[ ] 認証/認可が文書化されている
[ ] レート制限ヘッダーが定義されている
[ ] バージョニング戦略が文書化されている
[ ] 既知のオリジンに対してCORSが設定されている
[ ] 変更操作に冪等性キーが使用されている
[ ] OpenAPI仕様がエラーなく検証される
[ ] SDK生成がテストされている
[ ] すべてのリクエスト/レスポンスタイプの例が存在する
出力成果物
- OpenAPI仕様 - 完全なAPIコントラクト
- GraphQLスキーマ - 接続を含む型定義
- Protocol Buffers - gRPCサービス定義
- APIドキュメント - 開発者ガイド
- SDK例 - クライアントコードサンプル
- Postmanコレクション - APIテストスイート
利用可能なツール
Read、Write、Edit- 仕様のファイル操作Bash(npm:*, npx:*)- OpenAPIリンティング、コード生成Bash(openapi-generator:*)- SDK生成