イラストで理解するAPI Gateway

はじめに

API Gatewayを触る際に、毎回用語の多さで頭が混乱します。
今回はそんなことが予想される未来の自分のために、よく使うAPI GatewayのREST APIを中心に記事を書いていきます。

API Gatewayの全体はふんわり理解してるけど、いまいちよく分かってないんだよな〜という方の一助になれば幸いです。

書いてないこと

websocket, オーソライザー, APIキー, 使用料プランなどなど細かいオプション機能については触れていません。

用語

まずはAPI Gatewayによく出てくる用語を並べてみます。

• リソース
• メソッド
• 統合リクエスト
• ステージ

などなど、よくわかりませんね。。。
大丈夫です、これから一つずつ図を使って解説していきたいと思います。

ちなみに今回はよくあるAPI Gateway + Lambdaという構成を意識して解説しています。
何となく全体像が掴めれば、他のパターンにも応用が効くかと思います。

全体像

まずは全体像を見てみます。
今の段階ではふ〜ん、そうなんだという感じで大丈夫です。

API Gatewayってなんだっけ？

まずは簡単にAPI Gatewayをおさらいしておきましょう。
API Gatewayはクライアント(フロント)からのリクエストをバックエンドに渡してくれる仲介役です。

リクエストの内容を変換したり、目的のバックエンドにリクエストを渡してくれます。

リソース

まずはリソースです。

リソースは、「パス」のことです。

例えばhttps://myshop.comというショップサイトを作成します。
この時、ログインのページはhttps://myshop.com/loginみたいなパスにすると思います。
この/loginに対してのリクエストを処理するために/loginというリソースを作成します。

実際にAPI Gatewayの画面でも作成してみましょう。
まずはリソースの作成から/loginを作成します。

これで/loginというパスが追加されました。

ちなみに、/というのはルートリソースです。
https://myshop.comのホームのページです。

これで新しいパスが設定されました。
しかし、まだパスが設定されただけで、このパスに対しての処理を設定していません。

どういうことかというと
パス(URL)が変わるということは、サーバーに対して新たなページをください！という要求(HTTPリクエスト)をするということです。

そのため、次にこの要求の部分の設定を「メソッド」で行います。

メソッド

では次にメソッドです。

メソッドとはHTTPメソッドのことです。
GET, POST, PUT, DELETE...などなど

このメソッドは各パス(リソース)毎に設定を行います。
上の画像の例では/loginに対してPOSTとGETが設定されています。

これはどういった動きをするかというと、

この図のように、パスは同じでもリクエスト時のメソッド毎に別のバックエンドを呼び出すことができます。

ではこちらもコンソール画面で作成してみます。
まずはメソッドを作成します。

次に使用するメソッドを選択します。

メソッドが作成できたので、どのバックエンドにデータを送るか設定します。
今回はLambdaにデータを渡すので、Lambda関数を選択して、送り先のLambda関数を選択します。

これでloginに対してのPOSTとGETメソッドの設定が完了しました。

では、次に各メソッドに対しての処理を設定していきます。

個人的には、リソースに対して複数のメソッド、メソッドに対して複数の設定
というように、どんどん設定が内包されていく感じが分かりにくいポイントだと感じました。

メソッドの設定

先ほど作成したメソッドを選択してみます。

すると、何やらよく分からない画面が出てきます。
構成要素はこの4つです。

• メソッドリクエスト
• 統合リクエスト
• 統合レスポンス
• メソッドレスポンス

左右の縦長四角は左がユーザー側、右がバックエンド側です。

ここでやっていることを大まかに説明すると、

どのようなデータを受け取るのか？どのようにバックエンドにデータを渡すか？
逆に、バックエンドから受けたデータをどのようにクライアントへ渡すか？

ということを設定します。
いまいち分かりづらいですね。
ではこれを図にします、まずは全体像です。

ごちゃごちゃしているので、一つずつみて行きましょう。
イラストはイメージなので特に深い意味はありません...

メソッドリクエスト

まずはクライアントからリクエストを受け取るフェーズです。

メソッドリクエストではクライアントから受けたリクエストがルールに基づいた内容になっているのか確認します。
例えば、URLクエリ文字列を指定して、その条件のクエリ文字列を含まないリクエストは通さない。といった設定が可能です。

統合リクエスト

次に、メソッドリクエストを通過したデータを統合リクエストで処理します。

ここでは、リクエストの転送先のバックエンドの選択。
また、データの形式を変換することができます。

例えば、クライアントからのリクエストがXML形式だった場合に、それをLambdaで処理するためにJSON形式に変換する。といった使い方ができます。

統合レスポンス

このフェーズではバックエンドから受けたレスポンスの内容を変換することができます。

例えば、先ほどの統合リクエストとは逆にJSON形式のレスポンスをXML形式に変換することも可能です。

他にもステータスコードをマッピングすることもできます。
成功したレスポンス全てを200 OKで返すのではなく、201 Createdなど、ステータスコードに意味を持たせることができます。

メソッドレスポンス

ここが最後のフェーズになります。

ここでは最終的にクライアントに返すレスポンスの内容を決めます。
レスポンスのヘッダやボディの内容を設定することができます。

ここまで長々と説明したのはメソッドの設定項目になります。
これはメソッドが複数になれば各メソッドに対して設定が必要になります。

それをふまえて、リソース、メソッド、メソッドの設定を図に表すとこんな感じになります。

ややこし〜い

ステージ

では次にステージという概念を見ていきます。
先ほど説明したリソース、メソッドの設定をしていく中で、例えばメソッドの一部分だけ変更したい！ということが考えられます。

この時、いきなり本番環境のメソッドを変更するのは危険ですね。
できれば開発環境、テスト環境で動作の確認をしたいところです。

そこで便利な機能が「ステージ」です。
ステージはバージョンと呼ばれたりもします。

各ステージ毎に先ほどまでのリソース、メソッドが紐づいています。
図にするとこんな感じです。

こうすることで、各開発環境毎に設定を行うことができます。
そして、各ステージ毎に別のエンドポイントを持っているため、テストも簡単に行えます。

発行されるURLには以下のように、ステージ名が含まれます。
https://myshop.com/dev/login
https://myshop.com/prod/login

これで最初に記載した全体像が完成です。

デプロイ

概要とはあまり関係ありませんが、API Gatewayを公開する上で最低限必要な項目なので説明しておきます。

デプロイはそのままの意味でAPI Gatewayを公開するために必要です。
デプロイを行うことでステージにエンドポイント(URL)が割り当てられます。

では実際にコンソール画面から操作してみます。
APIのデプロイを選択します。

次にデプロイする際のステージを選択します。(新規作成も可能)
今回はdev(開発環境)というステージをデプロイします。

これでデプロイが完了です！簡単ですね！
画面の上部に発行されたURLがAPI Gatewayのエンドポイントになります。

エンドポイントに接続できることも確認しておきます。
Lambdaは"Hello from Lambda!"を返すだけの簡単な関数です。

できましたね。
この時、URLの最後にdev/loginとなっているのはステージとリソースの設定によるものです。
実際に発行されるURLは~/devまでなので/loginをつけ忘れないように気をつけましょう。

まとめ

全体的にざっくりと説明しましたが、できれば流れを掴んだ上でAPI Gatewayのコンソール画面を確認することをオススメします。
流れを理解した上で見てみると、それぞれのフェーズの動きがより理解しやすくなると思います。

参考資料

https://dev.classmethod.jp/articles/what-does-amazon-api-gateway-do/