API Gateway のポータルサイトを簡単に構築できるサーバーレスアプリを試す

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

10月29日にアナウンスがあったこちらを試してみました。

どういう仕組みか簡単に述べると、

  1. aws-api-gateway-developer-portal をデプロイすると ポータルサイトのS3バケットコンテンツ(swaggerファイル)用のS3バケット が生成される
  2. API Gateway で、swaggerファイルをエクスポートする
  3. 1で生成された コンテンツ用のS3バケット に swagger ファイルをアップロードする

ポータルサイトは S3 の静的ウェブサイトホスティングで公開されており、そこにアクセスするとAPI仕様を見ることができる、というものでした。触った感触だと、API Gateway ですでに構築された APIの仕様をすばやく展開できるため、一般公開しているAPIの仕様を見てもらう用途で活躍しそうです。

本記事では、手順に沿って既存の API Gateway の API 仕様をポータルサイトに載せるところまでやってみます。最終的には以下のようなサイトにアクセスできるようになります。

output.png

利用したもの

開発者ポータルを作成する

先にサイトを構築してから swagger ファイルをアップロードしていく方式のため、まずは開発者ポータルを構築します。

AWS SAM

インストールします。私の環境では npm でインストールした古い AWS SAM が残っていたのでまずはそれの掃除からやりました。

npm uninstall -g aws-sam-local

次に pip で最新の AWS SAM CLI をインストールします。

pip install --user aws-sam-cli

pip のユーザーディレクトリにパスを通します。fish shell の場合は以下。

## anyenv - pyenv init - fish
#### pyenv の設定…
#### pyenv の設定…
set user_base_path (python -m site --user-base)
set -x PATH $user_base_path/bin $PATH

sam コマンドが叩ければOKです。

sam --version
SAM CLI, version 0.6.1

開発者ポータルソースコードリポジトリを clone してデプロイ

まずこのリポジトリを clone します。

ghq get git@github.com:awslabs/aws-api-gateway-developer-portal.git

次に、AWS SAM CLI を使ってデプロイします。このとき、{your-lambda-artifacts-bucket-name}、つまりテンプレートファイル用のバケットをあらかじめ作っておきます。{your-lambda-artifacts-bucket-name}{custom-prefix} は各々の環境に合うよう置き換えてください。

sam package --template-file ./cloudformation/template.yaml --output-template-file ./cloudformation/packaged.yaml --s3-bucket {your-lambda-artifacts-bucket-name}

sam deploy --template-file ./cloudformation/packaged.yaml --stack-name "dev-portal" --capabilities CAPABILITY_NAMED_IAM --parameter-overrides DevPortalSiteS3BucketName="{custom-prefix}-dev-portal-static-assets" ArtifactsS3BucketName="{custom-prefix}-dev-portal-artifacts"

これを実行すると開発者ポータルのサイトができあがります。マネジメントコンソールの CloudFormation をみてみましょう。dev-portal というスタックがあるはずです。

dev-portal-output.png

いろいろなリソースを作っているみたいですね。 WebsiteURL がポータルサイトのURLなのでアクセスしてみましょう。

portal.png

ポータルサイトにアクセスできればOKです。

API Gateway の swagger ファイルをコンテンツとしてアップロード

次はポータルサイトにコンテンツを上げます。

  1. API Gateway の API を作成し、デプロイする
  2. APIキーを発行する
  3. swagger エクスポートする

という流れです。APIキーは、ポータルに登録・ログインすることで利用者が見られるようになります。そうして手に入れたAPIキーを使って、公開されているAPIにアクセスします。

API Gateway の API を作成する

簡単なAPIを定義しました。デプロイまでやってしまいます。

api_gateway.png

APIキーを発行する

API Gateway > Usage Plans で利用プランを作成します。先程デプロイしたAPIのステージに関連付けます。動作確認目的ですので、利用レートなどはなんでもOKです。premium プランを作成しました。

api_usage.png

API Gateway > API Keys で新しいAPIキーを作成します。先程作成した premium プランを関連付けます。

api_keys.png

swagger ファイルをエクスポートする

API Gateway > 作成した API > Stages > エクスポートしたいステージ > Export タブと選んで、「Export as Swagger + API Gateway Extensions」を選んでjsonファイルをダウンロードします。

api_export.png

コンテンツアップロード

あとは、エクスポートしたファイルをアップロードします。アップロード先は決まっていて、sam deploy のときに指定した ArtifactsS3BucketName="{custom-prefix}-dev-portal-artifacts" の catalog フォルダです。

api_s3.png

ポータルサイトにアクセスしてみましょう。上部メニューから「API」を選びます。アップロードしたAPIの定義が swagger UI で見られるはずです。

output.png

さらに、ここから RegisterSignIn を行うことでAPIキーが取得でき、ポータルサイトへ訪れた人が実際にAPIを叩くことができます。

まとめ

APIのポータルサイトを構築し、そこへ API Gateway で作成したAPI定義をアップロードして閲覧することができました。一般公開するAPIの仕様を見せる場所としてお手軽に構築でき、APIの開発者はドキュメント作成などの作業に時間を取られることがありません。

ポータルサイトのリポジトリによるとカスタマイズもできるようですので、引き続き以下のようなことについて試してみたいと思います。

  • ポータルサイトのUIをカスタマイズする
  • サインインしたユーザーのみにAPIを見せる、といったことができるか
  • S3の前段に CloudFront を挟めるか(WAFをアタッチしてIPアドレス制限などができるようになるため)
  • API Gateway から出力したものではない swagger ファイルでもいけるかどうか

クローズドなAPIについてもこの仕組で安心して利用できることがわかれば、用途が広がりそうですね。

参考