api-gateway

Amazon API Gateway の開発

Amazon API Gateway を使用して API を構築、管理、統制、運用するための専門的なガイダンスです。REST API（v1）、HTTP API（v2）、WebSocket API を対象としています。

このスキルの使い方

API Gateway に関する質問に回答する際は、次の手順に従ってください。

1. 回答する前に、関連するリファレンスファイルを確認してください。この概要だけを頼りにしないでください。
2. 複数の懸念事項にまたがるタスク（例：「mTLS とカスタムドメインを使用するプライベート API」）では、関連するすべてのリファレンスを確認してください。
3. ユーザーが IaC テンプレートを必要としている場合は、references/sam-cloudformation.md または references/sam-service-integrations.md を参照し、完全に動作する SAM／CloudFormation YAML を提示してください。
4. ユーザーの設計に影響する関連する落とし穴や制限事項について、必ず説明してください。

すばやく選ぶ：どの API タイプを使うか？

まず、適切な API タイプを選択してください。この判断は、その後のすべての選択に影響します。

REST API は、エンタープライズ向けのフル機能 API 管理プラットフォームです。組織が API を大規模に構築、公開、管理するために必要なガバナンス、セキュリティ、収益化、運用管理機能を提供します。これには、コンシューマーごとのスロットリングとクォータを設定できる使用量プラン、API キー、リクエスト検証、WAF 統合、リソースポリシー、キャッシュ、カナリアデプロイ、プライベートエンドポイントが含まれます。

HTTP API は、よりシンプルな API ワークロードに最適化された、軽量で低コストなプロキシです。コストを約 70％削減し、レイテンシーも低くなりますが、API 管理機能は利用できません。Lambda または HTTP バックエンド向けの、高速で軽量なプロキシが必要で、上記のエンタープライズ向け管理機能が不要な場合は、HTTP API を選択してください。

要素	REST API (v1)	HTTP API (v2)	WebSocket API
位置付け	フル API 管理	低コストのプロキシ	リアルタイム双方向通信
コスト	高め	約 70％安価	メッセージ単位の料金
レイテンシ	高め	低め	持続的な接続
最大タイムアウト	50ms-29s (Regional/Private では最大 300s)	30s の固定上限	29s
ペイロード	10 MB	10 MB	128 KB のメッセージ / 32 KB のフレーム
API 管理
使用量プラン/API キー	あり	なし	なし
リクエストの検証	あり (JSON Schema draft 4)	なし	なし
キャッシュ	あり (0.5-237 GB)	なし	なし
カスタムゲートウェイレスポンス	あり	なし	なし
VTL マッピングテンプレート	あり	なし (パラメータマッピングのみ)	あり
セキュリティとガバナンス
WAF	あり	なし (CloudFront + WAF を使用)	なし
リソースポリシー	あり	なし	なし
プライベートエンドポイント	あり	なし	なし
mTLS	あり (Regional カスタムドメインのみ)	あり (Regional カスタムドメインのみ)	CloudFront ビューアーの mTLS 経由
認証
Lambda オーソライザー	あり (TOKEN + REQUEST)	あり (REQUEST のみ、シンプル形式 + IAM ポリシー形式)	あり ($connect の REQUEST のみ)
JWT オーソライザー	なし (Cognito オーソライザーを使用)	あり (ネイティブ)	なし
Cognito オーソライザー	あり (ネイティブ)	JWT オーソライザーを使用	なし
運用
カナリアデプロイ	あり	なし	なし
レスポンスストリーミング	あり	なし	なし
X-Ray トレース	あり	なし	なし
実行ログ	あり	なし	あり
カスタムドメインの共有	WebSocket とは不可	WebSocket とは不可	REST/HTTP とは不可
REST API を使用する場合：外部の利用者、パートナー、またはマルチテナントプラットフォーム向けの API を構築するとき、利用者ごとにレート制限とクォータを適用する必要があるとき、API レイヤーでリクエストの検証、キャッシュ、または WAF が必要なとき、プライベートエンドポイント、リソースポリシー、またはカナリアデプロイが必要なとき、あるいは収益化やガバナンス要件を伴う API プロダクトを構築するときに使用します。

HTTP API を使用する場合：軽量な API やシンプルなバックエンドプロキシを構築するとき、コストとレイテンシが最優先事項であるとき、API レイヤーで利用者ごとのスロットリング、リクエストの検証、キャッシュ、または WAF が不要なとき、またネイティブの JWT 認可と OIDC／OAuth 2.0 で認証要件を満たせるときに使用します。30 秒の厳格なタイムアウトと API 管理機能がないことを受け入れてください。WAF、エッジキャッシュ、またはエッジコンピューティングを利用する場合は、HTTP API の前段に CloudFront ディストリビューションを配置します。

WebSocket API が必要な場合：リアルタイムのユースケース（チャット、通知、ライブダッシュボード）で、双方向の永続接続が必要なときに使用します。

手順

ステップ 1：API を設計する

実装の前に、要件を体系的に収集します。エンドポイント、認証、データモデル、パフォーマンス、セキュリティ、デプロイ要件を網羅する要件収集ワークフローの全容については、references/requirements-gathering.md を参照してください。

主な設計上の決定事項：

1. API タイプ：上記の判断表を使用します
2. エンドポイントタイプ：エッジ最適化（グローバルなクライアント向けのデフォルト。CloudFront POP を介して TCP 接続を最適化しますが、エッジではキャッシュしません）、リージョナル（同一リージョンのクライアント向け、またはエッジキャッシュ、エッジコンピューティング、きめ細かな WAF 制御、地理ベースのルーティングのために独自の CloudFront ディストリビューションを必要とするグローバルなクライアント向け）、プライベート（VPC 専用アクセス。REST API のみ）
3. トポロジ：集中型（単一ドメイン、パスベースのルーティング）と分散型（サービスごとのサブドメイン）
4. 認証：判断ツリーについては references/authentication.md を参照してください

ステップ 2：API を実装する

構築する内容に応じて、以下のリファレンスを参照してください。

• アーキテクチャパターン：references/architecture-patterns.md：トポロジ、マルチテナント SaaS、ハイブリッドワークロード、プライベート API、マルチリージョン、ストリーミング
• WebSocket API：references/websocket.md：ルート選択、@connections の管理、セッション管理、クライアントのレジリエンス、SAM テンプレート、制限、マルチリージョン
• サービス統合：references/service-integrations.md：AWS サービスとの直接統合（EventBridge、SQS、SNS、DynamoDB、Kinesis、Step Functions、S3）、HTTP プロキシ、モック、VTL マッピングテンプレート、バイナリメディアタイプ、Lambda の同期／非同期呼び出し
• カスタムドメインとルーティング：references/custom-domains-routing.md：ベースパスマッピング、ルーティングルール、ヘッダーベースのバージョニング
• セキュリティ：references/security.md：mTLS（API Gateway ネイティブ + CloudFront ビューワー mTLS）、TLS ポリシー、リソースポリシー、WAF、HttpOnly Cookie、CRL チェック
• SAM／CloudFormation：references/sam-cloudformation.md：IaC パターン、OpenAPI 拡張、VTL リファレンス、バイナリデータ
• SAM サービス統合テンプレート：references/sam-service-integrations.md：EventBridge、SQS、DynamoDB CRUD、Kinesis、Step Functions（REST + WebSocket）テンプレート

ステップ 3：パフォーマンスとスケーリングを設定する

• スロットリング：アカウントレベルのデフォルトは 10,000 rps／バースト 5,000 です（変更可能です。上限の引き上げは AWS Support に申請してください）。使用量プランを使って、ステージレベルおよびメソッドレベルのスロットリングを設定します。references/performance-scaling.md を参照してください。
• キャッシュ（REST のみ）：デフォルトの TTL は 300s、最大は 3600s です。デフォルトでは GET メソッドのみがキャッシュされます。キャッシュ可能なレスポンスの最大サイズは 1 MB です。
• エッジキャッシュ（すべての API タイプ）：エッジキャッシュには、リージョナル API の前段にセルフマネージドの CloudFront ディストリビューションを配置します。CloudFront はレイテンシー、バックエンドの負荷、そしてコストを削減します（キャッシュされたレスポンスは API Gateway に到達しません）。また、エッジコンピューティング（CloudFront Functions、Lambda@Edge）や、パスごとのきめ細かなキャッシュ動作も利用できます。独自の CloudFront ディストリビューションと組み合わせる場合は、エッジ最適化エンドポイントではなくリージョナルエンドポイントを使用します。
• スケーリング：API Gateway は自動的にスケーリングしますが、スタック全体（Lambda の同時実行数、DynamoDB のキャパシティ）を計画してください。

ステップ 4：可観測性を設定する

アクセスログは必ず設定してください。REST API と WebSocket API では、実行ログも有効にしてください（本番環境では ERROR レベル、デバッグ時のみ INFO）。HTTP API は実行ログをサポートしていません。代わりに、拡張された可観測性変数を使ったアクセスログを使用してください。

必要に応じて、以下の可観測性に関するリファレンスを参照してください。

• ログの設定、ログ形式、保持期間：references/observability-logging.md
• メトリクス、アラーム、メトリクスフィルター、X-Ray トレース：references/observability-metrics-alarms.md
• ログ分析とインサイト、分析パイプライン、クロスアカウント、コントロールプレーンログ：references/observability-analytics.md

ステップ 5：デプロイする

• 本番環境では Infrastructure as Code（SAM、CDK、CloudFormation、Terraform）を使用します。
• カナリアデプロイ（REST のみ）：トラフィックの一部を新しいバージョンにルーティングしてテストします。
• ブルー／グリーンデプロイ：カスタムドメインの API マッピングを使用して、ダウンタイムなしで環境を切り替えます。
• ルーティングルール（新しいドメインでは推奨）：カスタムドメインで宣言的なヘッダー／パスベースのルーティングを行い、バージョン管理、A/B テスト、段階的なロールアウト、セルベースのルーティングに利用します。
• 詳細なパターンについては、references/deployment.md を参照してください。

ステップ 6：ガバナンスを適用する

組織全体の API 標準については、以下を扱う references/governance.md を参照してください。

• 予防的コントロール（SCP、IAM ポリシー）
• 事前対応型コントロール（CloudFormation Hooks、Guard ルール）
• 検出的コントロール（AWS Config ルール、EventBridge）
• セキュリティ、可観測性、管理に関する具体的な適用例

回答形式

API Gateway に関する質問に回答する際は、次の構成にしてください。

1. 推奨事項：推奨するアプローチとその理由を最初に示します。
2. コード：ユーザーが実装を必要としている場合は、SAM／CloudFormation の YAML またはコードを含めます（必ず、最初に該当するリファレンスファイルを読んでください）。
3. 注意点：以下の落とし穴、または references/pitfalls.md に記載された関連事項を警告します。
4. 制限事項：設計に制約を与えるサービスの制限事項に触れます。

トラブルシューティングのクイックリファレンス

API Gateway のエラーを診断する際は、詳細な解決手順が記載されている references/troubleshooting.md を参照してください。特によくある問題は次のとおりです。

エラー	最も一般的な原因	すぐにできる対処法
400 Bad Request	ALB とのプロトコル（HTTP/HTTPS）の不一致	リスナーの種類にプロトコルを合わせます
401 Unauthorized	トークンの種類（ID トークンとアクセストークン）の誤り、または ID ソースの不足	トークンの種類がスコープ設定と一致していることを確認し、すべての ID ソースが送信されていることを確認します
403 Missing Auth Token	カスタムドメインの使用時に URL にステージ名が含まれている	URL パスからステージ名を削除します
403 from VPC	VPC エンドポイントのプライベート DNS がすべての API 呼び出しを傍受している	パブリック API にはカスタムドメイン名を使用します
403 Access Denied	リソースポリシーと認証タイプの不一致、または再デプロイの不足	ポリシーを確認し、認証タイプを確認して、API を再デプロイします
403 mTLS	証明書の発行元がトラストストアにない、または署名アルゴリズムが脆弱	CA がトラストストアにあることを確認し、SHA-256 以上を使用します
429 Too Many Requests	アカウント、ステージ、またはメソッドのスロットリング制限を超過	ジッター付き指数バックオフを実装し、上限の引き上げを申請します
500 Internal Error	Lambda の呼び出し権限が不足している（特にステージ変数を使用している場合）	Lambda 関数にリソースベースのポリシーを追加します
502 Bad Gateway	Lambda のレスポンスが必要なプロキシ形式ではない	Lambda から {statusCode, headers, body} を返します
504 Timeout	バックエンドが 29 秒（REST、延長可能）または 30 秒（HTTP、固定）を超過します。HTTP API の本文には "Service Unavailable" と記載されますが、ステータスは 504 です	バックエンドを最適化し、タイムアウト延長（REST Regional/Private）を申請するか、非同期呼び出しに切り替えます
CORS errors	Gateway Responses（4XX/5XX）に CORS ヘッダーがない	DEFAULT_4XX と DEFAULT_5XX のゲートウェイレスポンスに CORS ヘッダーを追加します
SSL/PKIX errors	バックエンドの証明書チェーンが不完全	証明書チェーン全体を指定し、insecureSkipVerification はテスト時にのみ使用します

重大な落とし穴

1. REST API のデフォルトのタイムアウトは29秒です（クォータ申請により、リージョナル／プライベートエンドポイントでは最大300秒まで延長できます）。Lambda の実行は継続しますが、クライアントには504が返されます。長時間の処理でユーザーエクスペリエンスを向上させるには、タイムアウトの延長を申請するか、非同期パターン（SQS、EventBridge）を検討してください。
2. HTTP API のハードタイムアウトは30秒です。Lambda の実行が継続する間、{"message":"Service Unavailable"} が返されます。
3. /ping と /sping は予約済みパスです。API リソースには使用しないでください。
4. 実行ログのイベントは1,024バイトで切り捨てられます。完全なデータを取得するにはアクセスログを使用してください。
5. 413 REQUEST_TOO_LARGE はカスタマイズできない唯一のゲートウェイレスポンスです。DEFAULT_4XX を包括的な設定として使用し、413を含むすべての4xxエラーにCORSヘッダーを追加してください。
6. REST API のリクエスト検証では、maxItems／minItems は検証されません。
7. OpenAPI のルートレベルの security は無視されます。操作ごとに設定する必要があります。
8. JWT オーソライザーの公開鍵は 2時間キャッシュされます。鍵のローテーションではこの点を考慮してください。
9. 管理 API のレート制限は、10 rps／バースト40です。大規模な自動化ではこの制限に達する可能性があります。
10. 設定を変更した後は、必ず REST API を再デプロイしてください。デプロイするまで変更は反映されません。
11. エッジ最適化エンドポイントはエッジでキャッシュしません。CloudFront POP を介してTCP接続を最適化するだけです。エッジキャッシュ、エッジコンピューティング（CloudFront Functions、Lambda@Edge）、またはCloudFrontの詳細な制御が必要な場合は、独自のCloudFrontディストリビューションを使用するリージョナル API を選択してください。

その他の落とし穴（ヘッダー処理、URLエンコード、キャッシュ料金、カナリアデプロイ、使用量プラン）については、references/pitfalls.md を参照してください。

IaC フレームワークの選択

デフォルト：CDK TypeScript

指定方法：

• 「use SAM」→ SAM／CloudFormation YAML テンプレートを生成
• 「use CloudFormation」→ CloudFormation YAML テンプレートを生成
• 「use Terraform」→ Terraform HCL を生成

指定がない場合は、必ず CDK TypeScript を使用してください。

エラーシナリオ

MCP サーバーが利用できない場合

• ユーザーに「AWS Serverless MCP が応答していません」と伝えます。
• 「MCP のサポートなしで続行しますか？」と尋ねます。
• ユーザーの確認なしに続行しないでください。

サービス制限のクイックリファレンス

完全な表については references/service-limits.md を参照してください。以下の数値クォータの多くはデフォルト値であり、調整可能です。アーキテクチャの決定に使用する前に、AWS アカウントチームと最新のクォータページで確認してください。主な制限：

リソース	REST API	HTTP API	WebSocket
ペイロードサイズ	10 MB	10 MB	128 KB
統合タイムアウト	50ms-29s（リージョナル／プライベートでは最大300s）	30s（ハード制限）	29s
リージョンあたりの API 数	600（リージョナル／プライベート）；120（エッジ最適化）	600	600
API あたりのステージ数	10	10	10
API あたりのルート／リソース数	300	300	300
カスタムドメイン（パブリック）	120	120	120
アカウントのスロットル	10,000 rps／バースト5,000	同じ	同じ（共有クォータ）
リージョンあたりの API キー数	10,000	該当なし	該当なし
リージョンあたりの使用量プラン数	300	該当なし	該当なし
キャッシュサイズ	0.5 GB - 237 GB	該当なし	該当なし