AWS API Gateway Developer Portal を使ってAPI定義を公開してみた

はじめに

AWS API Gatewayの設定をドキュメントとして公開するための手法を模索していたのですが、AWSの公式ドキュメントにも記載がある、「API Gateway Developer Portal」が非常に簡単に高品質なものを提供できます。
今回は「デプロイ方法」や「機能」などを紹介していきます。

「AWS API Gateway Developer Portal」とは？

「API Gateway Developer Portal」は、AWSコンソールでAPI Gatewayのリソースを確認せずとも、APIを公開することができる、AWSの公式ドキュメントにも記載されているアプリケーションです。
こちらはデプロイを実施した同一アカウント・同一リージョンのAPIGatewayのリソースを公開できる他に、OpenAPIの定義ファイル(JSON,YAML)をアップロードすることで、APIGatewayで管理されていないAPIを公開することも可能です。

「API Gateway Developer Portal」は、CloudFront / API Gateway / Lambda / Cognito / DynamoDB / S3等のサービスで構成されており、こちらのGitHubでソースコードも公開されています。

APIの表示に関する管理はもちろんなのですが、Cognitoを使ってユーザ管理（一般ユーザ/管理ユーザ）も可能になっており権限分離も行うことができます。

デプロイ方法

Setup にある通り、SAR(Serverless Application Repository) / SAM(Serverless Application Model) / development scripts によるデプロイ方法がありますが、今回はSAMによるデプロイを実施します。

SARによる実行はNode.jsのバージョンが12.xを利用するようになっており、バージョンが古すぎるためデプロイに失敗しますので注意してください。

事前準備

実行にはSAMが必要となります。
今回はCloud9から環境を作成します。

Cloud9を開き、「環境を作成」を押下します。
各設定内容を入力・選択してCloud9を作成します。

下記の通り、Cloud9のサブネットはインターネットへのルート必須なので注意してください。

作成完了したら、「EC2インスタンスの管理」からEC2に移動してIAMロールにSAMデプロイ用の権限を付与します。
今回は「AdministratorAccess」を付けておきます。

EC2が利用しているIAMロールに移動したら、「ポリシーをアタッチ」から、AdministratorAccessを付与してください。

IAMロールの更新が完了したら、Cloud9のコンソールに戻り、
「Cloud9で開く」から接続します。

今回起動したCloud9の各バージョンは下記の通りです。

OS: Amazon Linux release 2023 (Amazon Linux)
AWS CLI: 2.15.10
SAM CLI: 1.99.0
Git: 2.40.1

デプロイ時に利用するS3バケットの作成

SAMデプロイで作成する資材を補完するためのS3バケット（プライベート）を作成します。

東京リージョンで、プライベートバケットであることを確認し、他設定はデフォルトで作成してください

このバケット名はSAMデプロイ時の引数でも利用するのでメモしておいてください。
今回私は「dev-portal-s3-sam-20240125」という名前のバケットを作成します。

ソースコードの取得

aws-api-gateway-developer-portalのGitからソースコードを取得します。

git clone https://github.com/ozuiev/aws-api-gateway-developer-portal.git

cloneしてきた作業ディレクトリに移動もしておきます。

cd aws-api-gateway-developer-portal/

SAMによるデプロイ

Cloud9のコマンドプロンプトから下記SAM CLIコマンドを実行してパッケージをS3にアップロードします。

「{YOUR_BUCKET_NAME}」は適宜作成したバケット名に修正してください。
私の場合は、「export YOUR_LAMBDA_ARTIFACTS_BUCKET=dev-portal-s3-sam-20240125」となります。

また、実行リージョンに合わせて「--region」も修正してください。

export YOUR_LAMBDA_ARTIFACTS_BUCKET={YOUR_BUCKET_NAME}
# export YOUR_LAMBDA_ARTIFACTS_BUCKET=dev-portal-s3-sam-20240125

sam package --region ap-northeast-1 
    --template-file ./cloudformation/template.yaml 
    --output-template-file ./cloudformation/packaged.yaml 
    --s3-bucket $YOUR_LAMBDA_ARTIFACTS_BUCKET

続いてsam deployを実行していきます。下記のようなコマンドを実行してください。
「{YOUR_CUSTOM_PREFIX}」には作成されるリソースにつく共通の名前になっています。適宜指定してください。
また、実行リージョンに合わせて「　--region」も修正してください。

YOUR_CUSTOM_PREFIX={YOUR_CUSTOM_PREFIX}
# YOUR_CUSTOM_PREFIX=20240125

sam deploy --template-file ./cloudformation/packaged.yaml 
    --region ap-northeast-1 
    --stack-name &quot;dev-portal-&quot;$YOUR_CUSTOM_PREFIX 
    --s3-bucket $YOUR_LAMBDA_ARTIFACTS_BUCKET 
    --capabilities CAPABILITY_NAMED_IAM 
    --parameter-overrides 
    DevPortalSiteS3BucketName=&quot;dev-portal-static-assets-&quot;$YOUR_CUSTOM_PREFIX 
    ArtifactsS3BucketName=&quot;dev-portal-artifacts-&quot;$YOUR_CUSTOM_PREFIX 
    CognitoDomainNameOrPrefix=$YOUR_CUSTOM_PREFIX

しばらくして「sam deploy」が完了すると。

Successfully created/updated stack – dev-portal-20240125 in ap-northeast-1

が表示されます。
これで、デプロイ完了となります。

動作確認

ここからは基本的な動作、画面を確認していきます。

ポータル画面

SAMの実行結果出力されている箇所に、CloudFrontのURLがありますのでそちらを押下します。

このような画面が表示されます。こちらが、ポータル画面のTOPになっています。

ユーザ作成・ログイン

右上のRegisterからユーザ作成を行い、メールに届く認証コードで認証するとユーザ作成・ログインが可能となります。

管理者ユーザの作成

「Cognito ユーザプール」の画面から「AdminsGroup」のグループを選択し、
「ユーザをグループに追加」から、管理権限を付与したいユーザを追加します。こちらで、ユーザを管理権限に昇格させることができます。

管理者になると、「Admin Panel」を表示することができ、ポータル上でAPIの管理やユーザ管理を行うことができるようになります。

「AWS API Gateway Developer Portal」でできること

作成されるコンポーネントの説明はこちらにあります。
詳細は別のブログにまとめようと思いますが、主な機能を紹介します。

Getting Started

 Create an account and subscribe to APIs
To use any of our APIs you must create a developer account. A developer account provides an API Key for accessing our APIs, a playground for testing our APIs, and API usage metrics. Create or sign in using the buttons in the top right.

After you create a new account, you will have a new API Key but it won&#039;t be linked to any of our APIs. To activate it for a particular API, navigate to APIs and find the API you want. Click subscribe. Your API Key is now subscribed to the API and you can make calls to its methods.

Depending on the API configuration, subscribing to one API may subscribe you to several APIs. These APIs may have related functionality or share a pricing plan. Requests against any of them will be counted together in your usage.

We know that figuring out how to use APIs can be hard. Use the “Try it out!” feature to get examples of the request and response shapes of our APIs. This makes an API call to the backend service using your API Key and provides a sample curl request with all necessary input parameters and the real response.

If you need your API Key for any reason, you can always find it on your dashboard after logging in.

 Monitor your usage
Typically each API has a usage limit set for each API Key. As you scale up your usage of the APIs, you can monitor your usage towards the limits on your dashboard.

 はじめに
アカウントを作成してAPIを購読する
APIを使用するには、開発者アカウントを作成する必要があります。開発者アカウントは、APIにアクセスするためのAPIキー、APIをテストするためのプレイグラウンド、APIの使用状況メトリクスを提供します。右上のボタンを使って作成またはサインインしてください。

新しいアカウントを作成すると、新しいAPI Keyが発行されますが、どのAPIにもリンクされていません。特定のAPIでAPIキーを有効にするには、APIに移動し、必要なAPIを見つけます。subscribeをクリックします。これでAPI KeyがAPIに登録され、そのメソッドを呼び出すことができるようになる。

APIの設定によっては、1つのAPIを購読すると複数のAPIを購読することができます。これらのAPIは、関連する機能を持っていたり、料金プランを共有していたりします。これらのAPIに対するリクエストは、使用量にまとめてカウントされます。

APIの使い方を理解するのは難しいかもしれません。APIのリクエストとレスポンスの形状の例を得るには、&quot;Try it out!&quot;機能を使用してください。これは、あなたのAPIキーを使用してバックエンドサービスにAPIコールを行い、すべての必要な入力パラメータと実際の応答を持つサンプルcurlリクエストを提供します。

何らかの理由でAPIキーが必要な場合は、ログイン後のダッシュボードでいつでも見つけることができます。

 使用量の監視
通常、各APIにはAPI Keyごとに使用量の上限が設定されています。APIの利用を拡大するにつれて、ダッシュボード上で制限値に対する利用状況を監視することができます。

APIs

管理画面で表示を有効にしたAPI Gatewayのリソース設定を確認することができます。
また、APIに対してリクエストを実行することもできます。

Admin Panel

こちらは管理者ユーザのみ表示可能な画面になっています。
「APIs」のタブでAPIGatewayリソースを選択する「API管理機能」や

作成済みユーザの確認・ユーザ招待といった「ユーザ管理機能」が行えます。

また、「Generic APIs」の「Add API」の箇所からYAML/JSONのインポートを実施すれば、OpenAPI/Swagger形式のAPI定義をインポートすることも可能となっています。

　ユーザのサインイン・サインアップ

ユーザ管理はCoginitoで行われており、ログイン画面や自己サインアップ画面も提供されております。

また、ログイン時にパスワードを忘れた場合でも、「Forgot your password」も実装されています。

まとめ

今回は、AWSコンソールでAPI Gatewayのリソースを確認せずとも、API定義を公開するために、AWSから提供されているアプリケーションである、「API Gateway Developer Portal」の作成・動作確認を実施しました。

今回の「API Gateway Developer Portal」を利用することで、API仕様の公開サイトを簡単に構築でき、API開発者もドキュメント作成などの手間を減らすことが可能になっています。
AWSコンソール上のAPIGatewayの設定だけでは要件が不足する場合、こういった選択肢もございますので、ぜひ検討してみてはいかがでしょうか？

AWS・クラウドのMSP スカイアーチネットワークス株式会社

AWS・クラウド導入における構築から監視・運用保守までをマネージドサービスで提供する、スカイアーチネットワークスの公式サイト。AWS・クラウドを始め、豊富なサーバー管理の経験と安心のセキュリティ対策、専門エンジニアの確かな知識で、お客様のビジネスの成長をサポートします。AWS・クラウド導入における構築から監視・運用保守までをマネージドサービスで提供する、スカイアーチネットワークスの公式サイト。AWS・クラウドを始め、豊富なサーバー管理の経験と安心のセキュリティ対策、専門エンジニアの確かな知識で、お客様のビジネスの成長をサポートします。

投稿者プロフィール

makuta: 2015年新卒入社のエンジニア。

AWSを使ったサーバレスアーキテクチャ・コンテナサービスの設計・構築を担当。