【備忘録・まとめ】AWS API Gateway 開発者ガイド

## 出典
[Amazon API Gateway 開発者ガイド](https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/welcome.html)

## まとめ

* APIを外部に公開するためのマネージド高機能HTTPプロキシサーバ
* 主な機能
    * APIの管理
        * 公開・バージョン管理
        * エンドポイントURIとリソースの対応
    * API利用者のアクセス管理および制限
        * 認証・認可の確認
        * 呼び出し回数
        * 発信元セグメントなど
    * AWS内部サービスを外部に公開する窓口
        * 内部サービスに対して、外部リクエストをプロキシするイベントソース

## 要点

実用に際して重要なものだけ抜粋、補足。

### Amazon API Gateway の概念

[Amazon API Gateway の概念](https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/api-gateway-basic-concept.html)

以下、主要なものだけ

* デプロイ
    * リソースおよびメソッドのポイントインタイムスナップショット
    * リリースされたAPIのスナップショット
* API 開発者
    * APIを開発しているAWSユーザー
* APIエンドポイント
    * エッジに最適化された API エンドポイント
        * CloudFront経由でデプロイされるエンドポイント
        * APIリクエストが最寄のCloudFront接続ポイント(POP)にルーティングされる
    * リージョンの API エンドポイント
        * APIリクエストが、CloudFrontディストリビューションを経由せず、リージョン固有のAPI Gatewayへ直接飛ぶ 
    * プライベート API エンドポイント
        * パブリックインターネットからは分離されていて、アクセス権限を付与されているAPI GatewayのVPCエンドポイントを使用してのみアクセスできる
* APIキー
    * APIを使用者を識別する英数字の文字列
    * APIキーをLambdaオーソライザーまたは使用量プランと一緒に使用して、APIへのアクセスを制御する
* ステージ
    * 例: 'dev'、'prod'、'beta'、'v2' など
    * ライフサイクル状態への論理的な参照
    * API ステージは API IDとステージ名によって識別される
* 統合リクエスト
    * API Gatewayへのリクエストから、バックエンドへのリクエスト（イベント）の形式にマッピングするAPI Gatewayのインターフェース
* 統合レスポンス
    * バックエンド → API Gateway APIに流れるデータ（ステータスコード、ヘッダ、ペイロード等）の対応を定義するインターフェース
* マッピングテンプレート
    * 「Velocity Template Language (VTL)」で表現されるスクリプト。統合リクエスト、統合レスポンスで使われる。
* メソッドリクエスト
    * 外部からAPI Gateway APIへのリクエストの形式（パラメータや本文）を定義するインターフェース
* メソッドレスポンス
    * API Gateway APIから外部へのレスポンス形式を定義するインターフェース
* モデル
    * リクエストまたはレスポンスペイロードのデータ構造を指定するデータスキーマ
    * ペイロードの検証にも使われる
* プロキシ統合
    * 簡略化された API Gateway 統合の設定
    * Lambdaプロキシ統合の場合、API Gatewayは、バックエンドのLambda関数への入力としてリクエスト全体を送信
* 使用量プラン
    * スロットリングとクォータ制限を設定
    * 個々のクライアントAPI キーに適用される

### アクセスコントロール

[API Gateway で API へのアクセスをコントロールする](https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/apigateway-control-access-to-api.html)

以下、主要なものにだけ補足。

* リソースポリシー
    * 特定のソース IP アドレスまたは VPC エンドポイントから API へのアクセスを許可または拒否するリソースベースのポリシー
* IAMロールとポリシー
    * IAMロールとポリシー記述言語で設定できる柔軟な権限定義
* Cross-Origin Resource Sharing (CORS)
    * クロスドメインのリソースリクエストへの API の応答を制御
* [Lambdaオーソライザー](https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)
    * APIメソッドへのアクセスを制御するために使用するLambda関数
    * かなり強力で多用途
* [Amazon Cognito ユーザープール](https://docs.aws.amazon.com/ja_jp/cognito/latest/developerguide/what-is-amazon-cognito.html)
* クライアント側 SSL 証明書
* 使用量プラン
    * APIキーによる、キー毎の利用頻度制限

### デプロイとステージ

* APIデプロイを作成し、ステージと関連付けることで、API利用者は各デプロイのAPIの機能を利用できるようになる。
* デプロイは各API実装のインスタンスのような概念
* ステージは各デプロイへのエイリアスのような概念

### [Canaryリリース](https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/canary-release.html)

* 1つのステージに対して2つデプロイを割り当て、そのステージへのリクエストを特定割合で2つのデプロイにランダムに振り分けられる

### [スロットリング](https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/api-gateway-request-throttling.html)

* API Gatewayの主要機能の1つで、詳細に把握すべき重要項目
* スロットリングの対象粒度毎に、メソッド辺り、クライアント辺り、アカウント辺りがある
* 設定された頻度を超える呼び出しがあると、その呼び出しを制限する

### 実際のAPI呼び出し

* Javascriptやその他のランタイムからAPI GatewayのAPIをコールする場合、一般的には認証や認可の確認が必要になるが、全部実装すると大変
* そのため、API Gatewayが各APIに合わせたSDKを自動生成してくれる仕組みにはなっているのだが、コレも結構面倒
* Node.jsなんかだと[この辺](https://github.com/kndt84/aws-api-gateway-client)が使いやすそう

### [APIにカスタムドメイン名を付ける](https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/how-to-custom-domains.html)

* デフォルトでは各リソースのエンドポイントとして`https://<api-id>.execute-api.<region>.amazonaws.com/<stage>`の規則に従ったURLが発行されるが、このホストのドメイン名を自前のものに差し替える事ができる
* ただし、SSL証明書をACMないし自前で準備したりする必要がある