はじめに

みなさんは、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の場合)