- 2025/6/1時点の情報
- AWS 公式ドキュメントで日本語化されていないページはChromeの翻訳にて引用
この記事でわかること
前提：「１つのREST APIの複数ステージ」を「１つのカスタムドメイン」にマッピングをするとき
- その方法とアクセスURLの使い分け（評価の方法）
- デフォルトエンドポイントタイプ無効化時の挙動
具体的なシチュエーションと結論
あくまで結論は一例です
シチュエーション：
１つのREST API の prod dev のステージに対して１つのカスタムドメインとマッピングするには、どのような設定を行い、どのようなURLで呼び分けるのか？
結論：
APIマッピングのベースパスにそれぞれ prod dev など分かりやすいパスを設定する。
ベースパスをもとにマッピングされいてるAPIのステージへルーティングされる。
シチュエーション： デフォルトエンドポイントタイプを「非アクティブ」にし、`prod`ステージのみに対してデプロイしたときは`dev`ステージではどのような挙動になるのか？
結論：
デプロイしたステージに関係なく、デフォルトエンドポイントを「非アクティブ」設定を行ったAPI内のステージは、デフォルトエンドポイントでの呼び出しが不可となる。
参考情報（この後のセクションで実際の検証）
REST API のカスタム ドメイン名に API ステージをマッピングする
参考①
APIマッピングを使用して、APIステージをカスタムドメイン名に接続します。これにより、トラフィックはカスタムドメイン名を通じてAPIに送信されます。
参考②
APIマッピングでは、API、ステージ、そしてオプションでマッピングに使用するパスを指定します。例えば、productionAPIのステージを にマッピングできます
https://api.example.com/orders
参考③
複数階層の API マッピングがある場合、API Gateway は 最も長く一致するパスを持つマッピング にリクエストをルーティングします。どの API を呼び出すか決定する際、API Gateway が参照するのは API マッピングで設定されたパスだけ であり、API 本体のルート定義は判定に含まれません。
ベースパスマッピングの取得
参考④
ベースパス
APIの呼び出し元がURLの一部としてドメイン名の後に指定する必要があるベースパス名です。この値は、単一のAPI内のすべてのマッピングにおいて一意である必要があります。呼び出し元がドメイン名の後にベースパス名を指定しないようにするには、「(none)」を指定します。
API Gateway のパブリック REST API のカスタム ドメイン名
参考⑤
カスタムドメイン名を使用すると、API のホスト名を設定し、ベースパス（例：myservice）を選択して代替 URL を API にマッピングできます。例えば、よりユーザーフレンドリーな API ベース URL は次のようになります。
https://api.example.com/myservice
参考⑥
APIのデフォルトエンドポイントを無効にすることができます。クライアントは引き続きデフォルトエンドポイントに接続できますが、403 Forbiddenステータスコードを受け取ります。
検証
事前情報
実際の値は異なるが記事上では以下と定義する。
- カスタムドメイン名：
customdomain.com - デフォルトエンドポイント：
default.execute-api.ap-northeast-1.amazonaws.com
その他
- API Gateway
- API名：domain-test-api
- プロトコル：REST API
- API エンドポイントタイプ：リージョン（東京）
０．カスタムドメイン設定前の動作確認
カスタムドメイン設定無し、デフォルトエンドポイント「アクティブ」
リソース
ステージ
【 dev ステージのデプロイ状態とレスポンス】
サマリー
レスポンス確認
https://default.execute-api.ap-northeast-1.amazonaws.com/dev/goodbye
https://default.execute-api.ap-northeast-1.amazonaws.com/dev/hello
【 prod ステージのデプロイ状態とレスポンス】
サマリー
レスポンス確認
https://default.execute-api.ap-northeast-1.amazonaws.com/prod/goodbye
https://default.execute-api.ap-northeast-1.amazonaws.com/prod/hello
1．カスタムドメインの設定
ベースパスの指定は任意であるが、分かりやすいようにステージ名と対応付けるよう設定
ステージ：dev → ベースパス：dev
ステージ：prod → ベースパス：prod
２．カスタムドメインでのアクセス確認
「 カスタムドメイン / ベースパス / リソースパス 」でアクセスを検証
- ベースパスに基づき対応するステージのAPIへルーティングされることを確認
- API Gateway が参照するのは API マッピングで設定されたパスだけ であり、
API 本体のルート定義は判定に含まれないことを確認
【 ベースパスdev指定】
https://customdomain.com/dev/goodbye
→ dev ステージ の goodbye
https://customdomain.com/dev/hello
→ dev ステージの hello
【ベースパスprod指定】
https://customdomain.com/prod/goodbye
→ prod ステージの goodbye
https://customdomain.com/prod/hello
→ prod ステージの hello
３．デフォルトエンドポイントでもアクセスできることを確認
デフォルトエンドポイント「アクティブ」のままのため、手順２のカスタムドメインに加えてデフォルトエンドポイント経由でもアクセスできることを確認
※hello リソースは割愛
【devステージ】
https://default.execute-api.ap-northeast-1.amazonaws.com/dev/goodbye
【prodステージ】
https://default.execute-api.ap-northeast-1.amazonaws.com/prod/goodbye
４．デフォルトエンドポイントを「非アクティブ」に設定
APIの設定から非アクティブに変更
非アクティブになっていることを確認
※設定反映には再デプロイが必要
APIの再デプロイを行う
今回はprodステージに対してデプロイ
→ この後、prodステージに対してデプロイしたがdevステージにも影響があるのか確認する
デプロイを確認
APIマッピングからも確認
→ この時点でdevステージも無効になっている（察し...）
５．再度 カスタムドメインとデフォルトエンドポイントでのアクセス確認
カスタムドメインでのアクセス確認
※２．カスタムドメインでのアクセス確認 と結果が同じであったため割愛
→ カスタムドメインでのアクセスには影響なし
デフォルトエンドポイントでのアクセス
【 dev ステージ】
https://default.execute-api.ap-northeast-1.amazonaws.com/dev/goodbye
https://default.execute-api.ap-northeast-1.amazonaws.com/dev/hello
【 prod ステージ】
https://default.execute-api.ap-northeast-1.amazonaws.com/prod/goodbye
https://default.execute-api.ap-northeast-1.amazonaws.com/prod/hello
いずれも以下の通り正常アクセスできないForbiddenを確認
※APIの設定のため、デプロイ対象のステージに依存することなく dev ステージでもデフォルトエンドポイントは無効化されることが確認できた。
６．dev ステージをAPIマッピングから削除する
７．アクセス確認
APIマッピング：prodステージのみ、デフォルトエンドポイント：非アクティブ の状態でそれぞれのアクセス結果を確認する。
【 dev ステージ】
https://default.execute-api.ap-northeast-1.amazonaws.com/dev/goodbye
https://default.execute-api.ap-northeast-1.amazonaws.com/dev/hello
https://customdomain.com/dev/goodbye
https://customdomain.com/dev/hello
デフォルトエンドポイント、カスタムドメイン、いずれも以下の通りForbidden
【 prod ステージ】
https://default.execute-api.ap-northeast-1.amazonaws.com/dev/goodbye
https://default.execute-api.ap-northeast-1.amazonaws.com/dev/hello
→ デフォルトエンドポイント「非アクティブ」のため Forbidden
https://customdomain.com/dev/goodbye
→ Goodbye prod from Lambda!
https://customdomain.com/dev/hello
→ Hello prod from Lambda!
カスタムドメインで正常アクセスを確認
【その他】
https://customdomain.com/hello
→ 該当するベースパスが無いためForbidden
まとめ
参考情報の通り以下の点が確認できた。
- （参考①~⑥）APIマッピングによってベースパスに基づき対象のAPIへルーティングする
- （参考③）API を呼び出すか決定する際、API Gateway が参照するのは API マッピングで設定されたパスだけ であり、API 本体のルート定義は判定に含まれない
- （参考⑥）APIのデフォルトエンドポイントを無効にすると403 Forbiddenステータスコードを受け取る
カスタムドメインの動き
https://customdomain.com/「dev」/hello
「dev」がAPIマッピング（ベースパス）として、どのAPIを呼ぶかを決定する。
hello以降が渡されてAPI内のリソースパスに基づき動作する。
今回は未検証であるが、以下の通りロンゲストマッチでリクエストをルーティングする。
デフォルトエンドポイントの非アクティブ（無効化）
- 設定を反映させるためにはAPIの再デプロイが必要
- その際デプロイ先のステージ以外のAPIに存在する全ステージが非アクティブとなる
以上！