AWS API Gateway Developer Portal を使ってみる

はじめに

• みなさんは、APIをチーム内で共有する際にどのような手法を取っているでしょうか？
• フロントエンド担当とAPI担当が別れているチームでのやりとりがスムーズに行く方法を検討している中で、AWSから提供されている「AWS API Gateway Developer Portal 」を使用しました。
• 以前に一度使用した時は使用開始になるまで色々と手順が多く、まだ使いにくい印象を持っていたのですが、2019年3月末にVersion３がリリースされ、AWSの各サービスと統合され非常に使いやすくなりました。
• Developerポータルを使ってみて非常に良いサービスだと感じましたので、どのようなことが出来るサービスなのか紹介したいと思います。

AWS API Gateway Developer Portal とは

• 「API Gateway Developer Portal 」とは、第三者にAPIを公開し利用出来るようにするために、AWSから提供されているアプリケーションです。
• 管理者専用のUI画面からAPI Gatewayで管理されているAPIを公開することができます。
  また、OpenAPIの定義ファイル(JSON,YAML)をアップロードすることで、API Gatewayで管理されていないAPIを公開することも可能です。
• 「API Gateway Developer Portal 」は、API Gateway / Lambda / Cognito / DynamoDB / S3 /CloudFront 等で構成されたサーバーレスWebアプリケーションとなり、画面はReactで構築されています。ソースは、GitHub上でApache 2.0ライセンスで公開されていますので、自由にカスタマイズすることも可能です。

API Gateway Portal のユーザ種別

• API Gateway Portalの利用者には以下の２種類が存在します
  • 一般ユーザー
  • 管理者ユーザー
• それぞれのユーザーでどんなことが出来るのかをご紹介します

Developerポータル利用者が出来ること

Developerポータルにアクセスする

• Developerポータルのサイトにアクセスする

• トップページには以下の内容のメッセージが表示されています。

探してビルドしましょう

『スタートアップガイド』を読んで、アプリケーションをすぐに起動して実行するための具体的な方法を学んでください。

どのようなAPIが提供されているかドキュメントを確認し、SDKを生成してみましょう。

サブスクリプションの管理や、現在の使用状況の確認、APIキーの取得、APIのテストを行うには、サインインしてください。

• 画面上部の「Getting Started(スタートアップガイド)」を見てみましょう

• スタートアップガイドには以下の内容が記載されています

「スタートアップガイド」
・アカウントの作成とAPIの購読
APIを使用するには、開発者アカウントを作成する必要があります。
開発者アカウントは、APIにアクセスするためのAPIキー、APIをテストするためのプレイグランド、およびAPIの使用状況を確認するためのメトリクスを提供します。
右上のボタンからアカウントの作成またはサインインを行いましょう。

新しいアカウントを作成すると、APIキーが新しく作成されますが、APIにはリンクされていません。
特定のAPIに対してキーをアクティブにするには、必要なAPIに移動して「購読(Subscribe)」をクリックします。
これで、APIキーがAPIに紐づけられ、そのメソッドを呼び出すことができます。

APIの構成によっては、1つのAPIにサブスクライブすると、複数のAPIにサブスクライブされる場合があります。
これらのAPIには、関連する機能がある場合や価格プランが共有されている場合があります。
これらのいずれかに対する要求は、使用時に一緒にカウントされます。

APIの使い方を理解するのは難しいことです。
「Try it!」機能を使用して、APIのリクエストおよびレスポンスの例を取得します。
これにより、APIキーを使用してバックエンド・サービスへのAPI呼び出しが行われ、必要なすべての入力パラメーターと実際の応答を含むサンプルcurlリクエストが提供されます。

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

・使用状況を確認する
通常、各APIには、APIキーごとに使用制限が設定されています。
ダッシュボードの使用状況でAPIの使用状況を確認することができます。

• 画面上部の「APIs」を見てみましょう

• ログインしていませんので何も表示されず、「公開されているAPIはありません」のメセージが表示されています。

---

ログインしていない状態では、これ以上の操作は出来ませんので、以下に記載の流れでアカウント作成しログインしましょう

---

利用者ユーザアカウントを作成する

• Developerポータルのサイトにアクセスし右上の「Register」をクリックする

• ユーザ名とパスワードを入力し「Sign up」をクリックすることでユーザアカウントが作成されます

• パスワードポリシーは管理者がCognitoで設定したパスワードポリシーい準拠します

ログインする

• 先ほど作成したユーザ名とパスワードを入力し「Sign In」をクリックすることでログインできます

• パスワードがわからなくなった場合はログイン画面の「Forgot your password?」をクリックし、ユーザ名を指定してパスワードリセットすることができます

利用可能なAPI/ドキュメントを確認する

• ログインした状態で「APIs」をクリックすると、利用可能なAPIの一覧が表示されます
  APIは購読可能/不可の２つのカテゴリで分けられています

• 左側のAPI一覧から対象のAPIを選択するとOpenAPI形式のドキュメントを参照することが出来ます

APIを購読(Subscribe)する

• APIドキュメントのEndpointの下の「Subscribe」をクリックすることで、対象のAPIを購読することができます。

• SubscribeすることでAPIキーがAPIに紐づけられて利用可能となります。
• 「Authorize」をクリックするとAPIキーが設定されていることが確認できます

APIをテスト実行する

• Subscribe状態のAPIドキュメントを開き、実行したいメソッドの「Try it!」をクリックします

• パラメータを任意の値に変更し「Execute」をクリックします

• 「response」部分に実行結果が表示されます
• 実行されたCurlコマンドも表示されます
  

SDKをダウンロードする

• APIドキュメントの「Download SDK」をクリックし、取得したいSDKのプログラミング言語を選択してください
• 現時点(2019年5月)では「Android」「JavaScript」「iOS(Objective-C)」「iOS(Swift)」「Java」「Ruby」のSDKが取得可能です

• 言語によっては次画面でSDK生成に必要な情報を入力し、ダウンロードを実行します(Androidの場合)

APIの利用状況を確認する

• 画面上部の「My Dashboard」をクリックすると、自身に発行されているAPIキーとAPIごとの利用状況を確認できます
  

• 「APIリクエスト使用量」と「残りのAPIリクエスト回数」が表示されます

管理者にフィードバックを送る

• 画面右下の「Got an Opinon？」をクリックします

• フィードバック内容を記載し「Submit」をクリックすることで、管理者にメールが送信されます

管理者パネルで出来ること

• 管理者ユーザでログインすると「Admin Panel(管理者パネル)」が選択できます

API Gatewayで管理されているAPIを公開する

• API Gatewayで管理されているAPIが一覧で表示されます

• Developerポータル利用者に公開したいAPIの「Displayed」の「False」をクリックし「True」に変更します
  

• API単位での公開、あるいはメソッド単位での公開も可能です

• 公開を停止する場合は「False」に変更すれば、DeveloperポータルからAPIは見えなくなります

APIを更新する

• API Gatewayの内容を更新しても、公開されているAPIは自動的には変更されません。最新の状態に更新するためには一覧の「Update」をクリックします

• これで公開されているAPI情報が更新されます

SDKの生成を可能にする

• APIを公開してもSDKの生成はデフォルトでは出来ないようになっています
• SDKの生成を可能とするには、API一覧の「Allow Generating SDKs」の「Disabled」をクリックして「Enabled」に変更します

• これで利用者はSDKのダウンロードが可能となります
• SDKの公開を停止する場合は「Disabled」に戻してください

API Gatewayで管理されていないAPIを公開する

• OpenAPI定義ファイルを用意することで、API Gatewayで管理されていないAPIを公開することができます

• OpenAPI2.0(Swagger)形式または 3.x形式のJSON/YAML/YMLファイルをアップロードすることで公開されます

• Generic APIsの「Add API」をクリックします

• OpenAPI2.0(Swagger)形式または 3.x形式のJSON/YAML/YMLファイルを選択し「Upload」をクリックします

• API Nameの箇所に追加したAPIが表示され、利用者がAPIを利用可能になります

• APIの公開を停止する場合は「Delete」をクリックし、Generic APIsから消すことで公開は停止されます

Developer Portal のセットアップ

Developerポータルの構築

• Developer Portalをセットアップする方法は、以下の２パターンあります

  • AWS Serverless Application Repository 使用
  • AWS SAM 使用

• セットアップ方法の解説は日本語化されたAWSドキュメントが用意されていますので、そちらを参照ください

管理者ユーザの追加

• 管理者ユーザを作成するためには、一度作成したユーザを管理者に昇格させる必要があります
• AWSコンソールのCognitoを開いて、対象のユーザを「dev-portalAdminsGroup」グループに追加します

さいごに

• v3.0リリース時はドキュメントが英語版しか準備されていませんせしたが、現時点では日本語版ドキュメントもあり、非常に使いやすくなっています
• 今回の記事で興味を持った方は是非一度Developerポータルを立ち上げてみてください。