Amazon API Gateway でカスタムドメインを使用してパスベースの API バージョニングを実装する - AWS 規範ガイダンス
概要前提条件と制限事項アーキテクチャツールベストプラクティスエピックトラブルシューティング関連リソース追加情報

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Amazon API Gateway でカスタムドメインを使用してパスベースの API バージョニングを実装する

Corey Schnedl、Marcelo Barbosa、Mario Lopez Martinez、Anbazhagan Ponnuswamy、Gaurav Samudra、Abhilash Vinod、Amazon Web Services

概要

このパターンでは、カスタムドメインの API マッピング機能を使用して Amazon API Gateway 用のパスベースの API バージョニングソリューションを実装する方法を示します。

Amazon API Gateway は、API を作成、配布、保守、監視、保護するために規模に関係なく使用できるフルマネージドサービスです。サービスのカスタムドメイン機能を使用すると、API ユーザーに提供できる直感的な URL を使用して、シンプルなカスタムドメイン名を作成できます。API マッピングを使用して、API ステージをカスタムドメイン名に接続することができます。ドメイン名を作成し、DNS レコードを設定したら、API マッピングを使用して、カスタムドメイン名を使用して API にトラフィックを送信します。

API が公開されると、コンシューマーに利用されます。パブリック API が進化するにつれて、そのサービス契約も新機能が反映されるように進化します。ただし、既存の機能を変更または削除することは賢明ではありません。重大な変更は、コンシューマーのアプリケーションに影響を与え、実行時にアプリケーションを破損する可能性があります。API バージョニングは、下位互換性を損なったり、契約に違反したりしないようにするために重要です。

API のバージョニングには、コンシューマーが簡単に採用できるようにするための明確な戦略が必要です。パスベースの URL を使用した API のバージョニングは、最も簡単で一般的に使用されるアプローチです。このタイプのバージョニングでは、バージョンは API URI の一部として明示的に定義されます。次の URL の例で、コンシューマーが URI を使用してリクエストのために API バージョンを指定する方法を示します。

https://api.example.com/api/v1/orders

https://api.example.com/api/v2/orders

https://api.example.com/api/vX/orders

このパターンでは、 を使用して、API 用のスケーラブルなパスベースのバージョニングソリューションのサンプル実装 AWS Cloud Development Kit (AWS CDK) を構築、デプロイ、テストします。 AWS CDK は、使い慣れたプログラミング言語を使用してクラウドアプリケーションリソースをモデル化およびプロビジョニングするオープンソースのソフトウェア開発フレームワークです。

前提条件と制限事項

前提条件

  • アクティブ AWS アカウント。

  • このパターンのサンプルリポジトリを使用し、Amazon API Gateway カスタムドメイン機能を使用するには、ドメインの所有権が必要です。Amazon Route 53 を使用して、組織のドメインを作成および管理できます。Route 53 を使用してドメインを登録または移管する方法については、Route 53 ドキュメントの「新しいドメインの登録」を参照してください。

  • API のカスタムドメイン名をセットアップする前に、 AWS Certificate Managerで SSL/TLS 証明書を準備する必要があります。

  • API エンドポイントにマッピングするために DNS プロバイダーのリソースレコードを作成または更新する必要があります。このマッピングを行わないと、カスタムドメイン名宛ての API リクエストが API Gateway に届きません。

制限事項

  • カスタムドメイン名はプライベート API ではサポートされていません。

  • カスタムドメイン名は、すべての AWS リージョン で 内で一意である必要があります AWS アカウント。

  • 複数のレベルで API マッピングを設定するには、リージョン別カスタムドメイン名と TLS 1.2 セキュリティポリシーを使用する必要があります。

  • API マッピングでは、カスタムドメイン名とマップされた API が同じ AWS アカウントにある必要があります。

  • API マッピングに含めることができるのは、文字、数字、および $-_.+!*'()/ の文字だけです。

  • API マッピングのパスの最大文字数は 300 文字です。

  • ドメイン名ごとに、複数のレベルで 200 個の API マッピングを設定できます。

  • TLS 1.2 セキュリティポリシーでは、HTTP API をリージョン別カスタムドメイン名にだけマッピングできます。

  • WebSocket APIs HTTP API または REST API と同じカスタムドメイン名にマッピングすることはできません。

  • 一部の AWS のサービス は では使用できません AWS リージョン。利用可能なリージョンについては、「AWS サービス (リージョン別)」を参照してください。特定のエンドポイントについては、「サービスエンドポイントとクォータ」を参照して、サービスのリンクを選択してください。

製品バージョン

アーキテクチャ

以下の図に、アーキテクチャのワークフローを示します。

API マッピングとカスタムドメインを使用してパスベースの API バージョニングソリューションを実装するワークフロー。

この図表は、以下を示すものです:

  1. API ユーザーが、カスタムドメイン名を使用して Amazon API Gateway にリクエストを送信します。

  2. API Gateway が、リクエストの URL に示されているパスに基づいて、ユーザーのリクエストを API Gateway の適切なインスタンスとステージに動的にルーティングします。次の表に、さまざまな URL ベースのパスを API Gateway のさまざまなインスタンスの特定のステージにルーティングする方法の例を示します。

    API

    ステージ

    パス

    デフォルトエンドポイント

    CalculationAPIv1

    api

    apiv1

    有効

    CalculationAPIv2

    api

    apiv2

    有効

    CalculationAPIvX

    api

    apivX

    有効

  3. 送信先 API Gateway インスタンスがリクエストを処理し、結果をユーザーに返します。

自動化とスケール

API のバージョンごとに個別の AWS CloudFormation スタックを使用することをお勧めします。このアプローチでは、カスタムドメイン API マッピング機能によって、ルーティング先にできるバックエンド API を完全に分離できます。このアプローチの利点は、別の API を変更するリスクを発生させることなく、API のさまざまなバージョンを個別にデプロイまたは削除できることです。このアプローチは、CloudFormation スタックを分離することで耐障害性を向上させます。また、HTTP エンドポイント AWS Lambda、 のアクションなど、API AWS Fargateのさまざまなバックエンドオプションも提供します AWS のサービス。

Gitflow などの Git 分岐戦略を分離された CloudFormation スタックと組み合わせて使用して、さまざまなバージョンの API にデプロイされるソースコードを管理できます。このオプションを使用すると、新しいバージョン用にソースコードを複製することなく、さまざまなバージョンの API を管理できます。Gitflow を使用すると、リリースの実行時に git リポジトリ内のコミットにタグを追加できます。それにより、特定のリリースに関連するソースコードの完全なスナップショットが作成されます。更新を実行する必要がある場合は、特定のリリースのコードをチェックアウトし、更新を行い、対応するメジャーバージョンと一致する CloudFormation スタックに更新済みのソースコードをデプロイできます。このアプローチでは、API の各バージョンには分離されたソースコードがあり、個別の CloudFormation スタックにデプロイされるため、別の API バージョンが破壊されるリスクが軽減されます。

ツール

AWS のサービス

  • Amazon API Gateway は、任意のスケールで REST、HTTP、WebSocket API を作成、公開、維持、監視、保護する上で役立ちます。

  • AWS Certificate Manager (ACM) は、 AWS ウェブサイトとアプリケーションを保護するパブリックおよびプライベート SSL/TLS X.509 証明書とキーの作成、保存、更新に役立ちます。

  • AWS Cloud Development Kit (AWS CDK) は、コードでクラウドインフラストラクチャを定義し、それをプロビジョニングするためのオープンソースのソフトウェア開発フレームワークです CloudFormation。このパターンのサンプル実装では、AWS CDK in TypeScript を使用します。TypeScript AWS CDK で を操作するには、Microsoft TypeScript コンパイラ (tsc)、Node.js、ノードパッケージマネージャー () などの使い慣れたツールを使用しますnpm。必要に応じて Yarn を使用できますが、このパターンの例では npm を使用します。AWS コンストラクトライブラリを構成するモジュールは、npm リポジトリの npmjs.org を介して配布されます。

  • CloudFormation は、 AWS リソースをセットアップし、迅速かつ一貫してプロビジョニングし、 AWS アカウント および 全体のライフサイクルを通じてリソースを管理するのに役立ちます AWS リージョン。

  • AWS Lambda は、サーバーのプロビジョニングや管理を行うことなくコードを実行できるコンピューティングサービスです。必要に応じてコードを実行し、自動的にスケーリングするため、課金は実際に使用したコンピューティング時間に対してのみ発生します。

  • Amazon Route 53 は、高可用性でスケーラブルな DNS ウェブサービスです。

  • AWS WAF は、保護されたウェブアプリケーションリソースに転送される HTTP と HTTPS リクエストをモニタリングできるウェブアプリケーションファイアウォールです。

その他のツール

  • Bruno はオープンソースの git フレンドリーな API テストクライアントです。

  • cdk-nag は、ルールパックを使用して AWS CDK アプリケーションのベストプラクティスをチェックするオープンソースユーティリティです。

コードリポジトリ

このパターンのコードは、GitHub の「path-based-versioning-with-api-gateway」リポジトリで入手できます。

ベストプラクティス

  • 堅牢な継続的インテグレーションおよび継続的デリバリー (CI/CD) パイプラインを使用して、 AWS CDKで構築された CloudFormation スタックのテストとデプロイを自動化します。この推奨事項の詳細については、「AWS Well-Architected DevOps のガイダンス」を参照してください。

  • AWS WAF は、Amazon API Gateway などのサービスと簡単に統合できるマネージドファイアウォールです。 AWS WAF は、このバージョニングパターンが機能するために必要なコンポーネントではありませんが、 API Gateway AWS WAF に を含めるセキュリティのベストプラクティスとしてお勧めします。

  • 古いバージョンの API を効率的に廃止し、削除できるように、API コンシューマーに定期的に最新バージョンの API にアップグレードするよう促します。

  • このアプローチを本番環境で使用する前に、API の認可戦略とファイアウォールを導入してください。

  • 最小特権アクセスモデル AWS アカウント を使用して、 の AWS リソース管理へのアクセスを実装します。

  • で構築されたアプリケーションのベストプラクティスとセキュリティに関する推奨事項を適用するには AWS CDK、cdk-nag ユーティリティを使用することをお勧めします。

エピック

タスク説明必要なスキル

リポジトリのクローン作成

次のコマンドを実行して、サンプルアプリケーションのリポジトリをクローン作成するには、次のコマンドを実行します。

git clone https://github.com/aws-samples/path-based-versioning-with-api-gateway
アプリ開発者

リポジトリのクローンを作成した場所にナビゲートします。

リポジトリのクローンを作成したフォルダに移動するには、次のコマンドを実行します。

cd api-gateway-custom-domain-versioning
アプリ開発者

必要な依存ファイルをインストールします。

必要な従属関係をインストールには、次のコマンドを実行します。

npm install
アプリ開発者
タスク説明必要なスキル

ルーティングスタックのデプロイを開始します。

CloudFormation ルーティングスタック CustomDomainRouterStack のデプロイを開始するには、次のコマンドを実行します。example.com は、所有しているドメインの名前に置き換えてください。

npx cdk deploy CustomDomainRouterStack --parameters PrerequisiteDomainName=example.com
注記

次のドメイン DNS 検証タスクが正常に実行されるまで、スタックのデプロイは成功しません。

アプリ開発者
タスク説明必要なスキル

ドメインの所有権を検証します。

証明書は、関連付けられたドメインの所有権を証明するまで、保留中の検証のステータスのままになります。

所有権を証明するには、ドメインに関連付けられているホストゾーンに CNAME レコードを追加します。詳細については、 AWS Certificate Manager ドキュメントの「DNS 検証」を参照してください。

適切なレコードを追加すると、CustomDomainRouterStack デプロイが成功します。

アプリ開発者、AWS システム管理者、ネットワーク管理者

API Gateway カスタムドメインを指すエイリアスレコードを作成します。

証明書が正常に発行および検証されたら、Amazon API Gateway カスタムドメイン URL を指す DNS レコードを作成します。

カスタムドメイン URL は、カスタムドメインのプロビジョニングによって一意に生成され、CloudFormation 出力パラメータとして指定されます。次の内容はレコードの例です。

ルーティングポリシー: シンプルルーティング

レコード名: demo.api-gateway-custom-domain-versioning.example.com

Alias (エイリアス): あり

レコードタイプ: AWS リソースを指す「A」タイプの DNS レコード

値: d-xxxxxxxxxx.execute-api.xx-xxxx-x.amazonaws.com

TTL (秒): 300

アプリ開発者、AWS システム管理者、ネットワーク管理者
タスク説明必要なスキル

ApiStackV1 スタックをデプロイします。

ApiStackV1 スタックをデプロイするには、以下のコマンドを実行します。

npm run deploy-v1

次の CDK コードは API マッピングを追加します。

var apiMapping = new CfnApiMapping(this, "ApiMapping", {
      apiId: this.lambdaRestApi.restApiId,
      domainName: props.customDomainName.domainName,
      stage: "api",
      apiMappingKey: "api/v1",
    });
アプリ開発者

ApiStackV2 スタックをデプロイします。

ApiStackV2 スタックをデプロイするには、以下のコマンドを実行します。

npm run deploy-v2
アプリ開発者

API を呼び出します。

Bruno を使用して API を呼び出し、API エンドポイントをテストするには、「追加情報」の手順を参照してください。

アプリ開発者
タスク説明必要なスキル

リソースをクリーンアップします。

このサンプルアプリケーションに関連付けられたリソースを破棄するには、次のコマンドを実行します。

npx cdk destroy --all
注記

ドメイン所有権の検証プロセスのために手動で追加した Route 53 DNS レコードを必ずクリーンアップしてください。

アプリデベロッパー

トラブルシューティング

問題ソリューション

証明書を検証できないため、CustomDomainRouterStack のデプロイがタイムアウトする。

前のタスクで説明したように、適切な DNS 検証 CNAME レコードが追加されていることを確認してください。新しい証明書は、DNS 検証レコードの追加後に、[保留中の検証] のステータスを最大 30 分間表示し続けます。詳細については、 AWS Certificate Manager ドキュメントの「DNS 検証」を参照してください。

関連リソース

  • Amazon CloudFront を使用したヘッダーベースの API Gateway バージョニングの実装 – この AWS コンピューティングブログ記事では、このパターンで説明されているパスベースのバージョニング戦略の代わりに、ヘッダーベースのバージョニング戦略を提供しています。

  • AWS CDK ワークショップ – この入門ワークショップでは、 を使用して AWS でアプリケーションを構築およびデプロイすることに重点を置いています AWS Cloud Development Kit (AWS CDK)。このワークショップでは、Go、Python、TypeScript をサポートしています。

追加情報

Bruno を使用した API のテスト

オープンソース API テストツールである Bruno を使用して、パスベースのルーティングがサンプルアプリケーションに対して適切に動作していることを検証することをお勧めします。このパターンでは、サンプル API のテストを容易にするサンプルコレクションを用意しています。

API を呼び出してテストするには、次の手順を実行します。

  1. Bruno をインストールします。

  2. Bruno を開きます。

  3. このパターンのコードリポジトリで、「Bruno/Sample-API-Gateway-Custom-Domain-Versioning」を選択し、コレクションを開きます。

  4. ユーザーインターフェイス (UI) の右上にある [環境] ドロップダウンを表示するには、コレクション内の任意のリクエストを選択します。

  5. [環境] ドロップダウンで、[設定] を選択します。

  6. REPLACE_ME_WITH_YOUR_DOMAIN 値をカスタムドメインに置き換えます。

  7. [保存] を選択し、[設定] セクションを閉じます。

  8. [サンドボックス環境] では、[アクティブ] オプションが選択されていることを確認します。

  9. 選択したリクエストの -> ボタンを使用して API を呼び出します。

  10. V2 と比較して V1 で検証 (数値以外の値を渡す) がどのように処理されるかに注意してください。

API 呼び出しの例と V1 と V2 の検証の比較のスクリーンショットを確認するには、このパターンのコードリポジトリの README.md ファイル内にある「サンプル API をテストする」を参照してください。