API Gateway 用語整理
API タイプ
API Gateway は3種類のAPIをサポートしている
| API タイプ | 説明 | 主なユースケース |
|---|---|---|
| REST API | フル機能のRESTful API | API キー、WAF、リクエスト検証、キャッシュが必要な場合 |
| HTTP API | 軽量・低コストのRESTful API | シンプルなLambda/HTTP統合、JWT認証 |
| WebSocket API | 双方向リアルタイム通信 | チャット、ゲーム、リアルタイムダッシュボード |
出典: Amazon API Gateway concepts
API Gateway is an AWS service that supports creating, deploying, and managing a RESTful application programming interface (API) to expose backend HTTP endpoints, AWS Lambda functions, or other AWS services.
Resource（リソース）
REST API における論理的なエンティティ
アプリケーションがリソースパスを通じてアクセスする対象を表す
/users ← リソース
/users/{userId} ← 子リソース（パスパラメータ付き）
/users/{userId}/orders
A resource is a logical entity that an app can access through a resource path
Method（メソッド）
リソースに対するアクション
HTTP メソッド（GET, POST, PUT, DELETE など）に対応する
GET /users ← ユーザー一覧取得
POST /users ← ユーザー作成
GET /users/{userId} ← 特定ユーザー取得
メソッドの認可設定
各メソッドにはAuthorizationTypeを設定し、アクセス制御を行う
| AuthorizationType | 説明 | AuthorizerId |
|---|---|---|
| NONE | 認可なし。誰でも呼び出し可能 | 不要 |
| AWS_IAM | IAM認証。SigV4署名が必要 | 不要 |
| CUSTOM | Lambda Authorizerで認証 | 必須 |
| COGNITO_USER_POOLS | Cognito User Poolで認証 | 必須 |
CUSTOMとCOGNITO_USER_POOLSを使う場合は、別途Authorizerリソースを定義し、AuthorizerIdで参照する
また、同じリソース（例: /users）でもメソッドごとに異なる認可設定が可能:
GET /users → AuthorizationType: NONE （誰でも一覧取得可能）
POST /users → AuthorizationType: AWS_IAM （認証ユーザーのみ作成可能）
Route（ルート）
HTTP API / WebSocket API における概念
REST API の「リソース + メソッド」に相当する
HTTP API:
GET /users
POST /users/{userId}
Integration（統合）
API Gateway とバックエンドを接続する設定
クライアント → API Gateway → [Integration] → バックエンド
├─ Lambda
├─ HTTP エンドポイント
├─ AWS サービス
└─ Mock
Integration Type（統合タイプ）
| タイプ | 値 | 説明 |
|---|---|---|
| Lambda Proxy | AWS_PROXY | Lambda に全リクエストをそのまま渡す（推奨） |
| Lambda Custom | AWS | マッピングテンプレートでデータ変換 |
| HTTP Proxy | HTTP_PROXY | HTTP エンドポイントにそのまま転送 |
| HTTP Custom | HTTP | マッピングテンプレートでデータ変換 |
| Mock | MOCK | バックエンドなしでレスポンスを返す |
出典: Choose an API Gateway API integration type
The Lambda proxy integration supports a streamlined integration setup with a single Lambda function. The setup is simple and can evolve with the backend without having to tear down the existing setup.
Proxy vs Custom Integration
Proxy Integration:
クライアント → API Gateway → Lambda（リクエストそのまま）
← Lambda（レスポンスそのまま）
Custom Integration:
クライアント → API Gateway → [Mapping Template] → Lambda
← [Mapping Template] ←
Stage（ステージ）
API のライフサイクル状態を表す論理的な参照
デプロイメントのスナップショットに名前を付けたもの
API
├─ dev ステージ → デプロイメント v1
├─ test ステージ → デプロイメント v2
└─ prod ステージ → デプロイメント v3
ステージごとに設定できる項目:
- キャッシュ設定
- スロットリング
- ログ設定
- ステージ変数
- Canary リリース
出典: Amazon API Gateway concepts
A logical reference to a lifecycle state of your API (for example, ‘dev’, ‘prod’, ‘beta’, ‘v2’). API stages are identified by API ID and stage name.
Deployment（デプロイメント）
API のスナップショット
ステージに関連付けることでクライアントが利用可能になる
API 変更 → デプロイメント作成 → ステージに関連付け → 公開
API デプロイ
APIを公開するためには、デプロイという操作が必要
デプロイの際は、必ず一つのステージを指定してデプロイが必要
## デプロイの概念
┌─────────────────────────────────────────────────────────────────┐
│ REST API (設計図) │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ /users │ │ /orders │ │ 新規追加 │ ← 編集中（未公開） │
│ │ GET │ │ GET │ │ DELETE │ │
│ │ POST │ │ POST │ │ │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
└───────────────────────────┬─────────────────────────────────────┘
│
│ デプロイ（スナップショット作成）
▼
┌─────────────────────────────────────────────────────────────────┐
│ デプロイメント │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ デプロイID: d1234 作成日時: 2025-12-10 14:00 │ │
│ │ 内容: /users (GET,POST,DELETE), /orders (GET,POST) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────┬─────────────────────────────────────┘
│
│ ステージに関連付け
▼
┌─────────────────────────────────────────────────────────────────┐
│ ステージ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ dev │ │ staging │ │ prod │ │
│ │ デプロイ:d1234│ │ デプロイ:d1233│ │ デプロイ:d1232│ │
│ │ (最新) │ │ (1つ前) │ │ (2つ前) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ https://xxx.execute-api https://xxx.execute-api │
│ .../dev/users .../prod/users │
└─────────────────────────────────────────────────────────────────┘
## 変更が反映されるタイミング
API編集 ──────────────────────────────────────▶ 反映されない
│
API編集 → デプロイ作成 ─────────────────────────▶ 反映されない
│
API編集 → デプロイ作成 → ステージに関連付け ────▶ ✅ 反映される
API ステージ
デプロイ内容は、ステージごとに履歴を保持する
- 例:
- ステージごとにアクセスURLが異なる
- prod ステージ: https://
.execute-api. .amazonaws.com/prod/… - staging ステージ: https://
.execute-api. .amazonaws.com/staging/… - dev ステージ: https://
.execute-api. .amazonaws.com/dev/…
- prod ステージ: https://
- prodステージへのデプロイで問題が起こった場合、prodステージ内のデプロイ履歴をもとにロールバック可能
- ステージごとにアクセスURLが異なる
REST API
リソース設定
URLパスの一部(/users、など)を指す
APIを作成すると、最上位に ”/” で表現されるリソースが作成される
その下に入れ子で複数のリソースを作成可能
各リソースにはメソッドを複数構成可能
例:
REST API
│
├── / (ルートリソース)
│ │
│ ├── /users (リソース)
│ │ ├── GET → Lambda: listUsers
│ │ ├── POST → Lambda: createUser
│ │ │
│ │ └── /{userId} (パスパラメータ付きリソース)
│ │ ├── GET → Lambda: getUser
│ │ ├── PUT → Lambda: updateUser
│ │ └── DELETE → Lambda: deleteUser
メソッド設定
リソースとメソッドの組み合わせごとに、以下の4つの設定を行う
- メソッドリクエスト
- 統合リクエスト
- 統合レスポンス
- メソッドレスポンス
イメージ図:
┌─────────────────────────────────────────────────────────────────────────────┐
│ API Gateway │
│ │
│ クライアント バックエンド │
│ (ブラウザ/ (Lambda/ │
│ アプリ) HTTP等) │
│ │
│ │ │ │
│ │ ①リクエスト │ │
│ ▼ │ │
│ ┌──────────────────┐ ┌──────────────────┐ │ │
│ │ メソッドリクエスト │ ──▶ │ 統合リクエスト │ ───────────────▶│ │
│ │ │ │ │ │ │
│ │ ・認証/認可 │ │ ・リクエスト変換 │ │ │
│ │ ・パラメータ検証 │ │ ・マッピング │ │ │
│ │ ・APIキー検証 │ │ ・バックエンド指定│ │ │
│ └──────────────────┘ └──────────────────┘ │ │
│ │ │
│ │ │
│ ┌──────────────────┐ ┌──────────────────┐ │ │
│ │ メソッドレスポンス │ ◀── │ 統合レスポンス │ ◀───────────────│ │
│ │ │ │ │ │ │
│ │ ・ステータスコード│ │ ・レスポンス変換 │ │ │
│ │ ・レスポンスヘッダ│ │ ・マッピング │ │ │
│ │ ・レスポンスモデル│ │ ・エラーハンドリング│ │ │
│ └──────────────────┘ └──────────────────┘ │ │
│ │ │
│ │ ④レスポンス │
│ ▼ │
│ クライアント │
└─────────────────────────────────────────────────────────────────────────────┘
Endpoint Type（エンドポイントタイプ）
API のホスト名の種類
| タイプ | 説明 | REST API | HTTP API |
|---|---|---|---|
| Edge-optimized | CloudFront 経由でグローバル配信 | ✓ | ✗ |
| Regional | 同一リージョンのクライアント向け | ✓ | ✓ |
| Private | VPC 内からのみアクセス可能 | ✓ | ✗ |
Edge-optimized:
クライアント → CloudFront POP → API Gateway（リージョン）
Regional:
クライアント → API Gateway（リージョン）
Private:
VPC 内クライアント → VPC Endpoint → API Gateway
出典: Choose between REST APIs and HTTP APIs
Authorizer（オーソライザー）
API へのアクセスを制御する認証・認可メカニズム
| タイプ | 説明 | REST API | HTTP API |
|---|---|---|---|
| IAM | IAM ロール/ポリシーで認可 | ✓ | ✓ |
| Cognito | Cognito User Pool のトークン検証 | ✓ | ✓（JWT経由） |
| Lambda | カスタム認証ロジック | ✓ | ✓ |
| JWT | JWT トークンのネイティブ検証 | ✗ | ✓ |
| Resource Policy | リソースベースのポリシー | ✓ | ✗ |
出典: Use API Gateway Lambda authorizers
A Lambda authorizer is a function that takes the caller’s identity as input and returns an IAM policy as output.
Lambda Authorizer の種類
Token-based:
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
↓
Lambda Authorizer（トークン検証）
Request-based:
Headers + Query Strings + Stage Variables + Context
↓
Lambda Authorizer（複数ソースで検証）
Canary Release（カナリアリリース）
本番ステージの一部トラフィックを新バージョンに振り分けるデプロイ戦略
prod ステージ
├─ Production Release (80%) → デプロイメント v1
└─ Canary Release (20%) → デプロイメント v2
出典: Set up an API Gateway canary release deployment
Canary release is a software deployment strategy in which a new version of an API is deployed for testing while the production release remains for normal operations.
Canary の設定場所
Canary 設定は Stage に対して行う。Stage が本番用とCanary用の2つの Deployment を参照する構造になる
REST API
│
├── Deployment (abc123) ← 本番用スナップショット
│
├── Deployment (xyz789) ← Canary用スナップショット
│
└── Stage (prod)
│
├── DeploymentId: abc123 ← 本番（80%のトラフィック）
│
└── CanarySetting
├── DeploymentId: xyz789 ← Canary（20%のトラフィック）
├── PercentTraffic: 20
└── StageVariableOverrides:
└── version: v2 ← Canary用にステージ変数を上書き
CloudFormation での設定例:
ApiStage:
Type: AWS::ApiGateway::Stage
Properties:
RestApiId: !Ref RestApi
StageName: prod
DeploymentId: !Ref ProductionDeployment # 本番用
Variables:
version: v1
CanarySetting: # ← Stage のプロパティとして設定
DeploymentId: !Ref CanaryDeployment # Canary用
PercentTraffic: 20
StageVariableOverrides:
version: v2CodeDeploy の Canary との違い
API Gateway の Canary は設定した割合を維持し続ける。CodeDeploy のように時間経過で自動的にトラフィックを移行する機能はない
| 項目 | API Gateway Canary | CodeDeploy Canary/Linear |
|---|---|---|
| トラフィック移行 | 手動で割合変更または昇格 | 時間経過で自動的に移行 |
| 設定例 | 20%を維持し続ける | 10%→5分後→100% |
| ロールバック | 手動でCanary無効化 | CloudWatch Alarmで自動ロールバック |
| 用途 | 長期間のA/Bテスト向き | 安全なデプロイ自動化向き |
Canary のログ出力
Canary リリースでは、本番とCanaryで別々の CloudWatch Logs ロググループにログが出力される
| ログの種類 | ロググループ名 |
|---|---|
| 本番の実行ログ | API-Gateway-Execution-Logs/{rest-api-id}/{stage-name} |
| Canary の実行ログ | API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}/Canary |
出典: Set up an API Gateway canary release deployment
The production stage execution log group is named
API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}and the canary release execution log group is namedAPI-Gateway-Execution-Logs/{rest-api-id}/{stage-name}/Canary.
Mapping Template（マッピングテンプレート）
リクエスト/レスポンスのデータ形式を変換するスクリプト
VTL（Velocity Template Language）で記述
Integration Request:
クライアントのリクエスト → [Mapping Template] → バックエンド形式
Integration Response:
バックエンドのレスポンス → [Mapping Template] → クライアント形式
出典: Amazon API Gateway concepts
A script in Velocity Template Language (VTL) that transforms a request body from the frontend data format to the backend data format