はじめに

アイレット25卒社員によるAWSブログリレーのAmazon API Gateway編です。
この記事ではAPI Gatewayの基礎知識をまとめてみました。前半では、初めてAPI Gatewayを触る方に向けて前提知識を整理し、後半では、実際のハンズオンを題材に実践的に理解を深めていきます。

本記事は、AWS Top Engineers のエンタープライズクラウド事業部構築第二セクションの新川貴章に監修いただきました。

API Gatewayとは？

API Gatewayとはあらゆる規模の「Web API」を簡単に作成・公開・管理することができるサービスです。

APIとは ： コンピュータ同士のやり取りを橋渡しするインターフェース

Web APIはhttpやhttpsなどのWeb技術を用いて実現されるAPIの一種です。そもそも、APIとはコンピュータ同士のやり取りを橋渡しするインターフェースです。例えば、図のようなアプリケーション（クライアント）が他のアプリケーションサーバ（アプリ）の機能を使いたい場合、クライアントとアプリサーバの橋渡しを行います。また、クライアントが送信するべきリクエストの形式と、それに伴うアプリサーバの挙動を定めているのはAPIです。よって、「物事をする方法、しかた。やりかた」という意味を持つ「仕様」としての側面もあります。

API Gatewayでは、
・クライアントのリクエストをアプリサーバのどのような処理に結びつけるのか
・クライアントのリクエストをアプリサーバが処理するために、リクエストをどのように翻訳するのか
を設定することで、クライアントとアプリサーバとのやり取りを橋渡しする役割を担います。

API Gatewayで提供されるWeb APIの種類

API Gatewayにおいて提供されるAPIのタイプは以下の3つがあります。

1｜HTTP API　　　　
2｜REST API
3｜WebSocket API

HTTP APIとREST APIは後ほど説明するRestful APIの特徴を（一部、あるいは全て※）持ちます。一方、WebSocket APIではWebSocketと呼ばれる通信プロトコルを用いることで、サーバとクライアント間で双方向接続を実現します。

※正確にはREST APIはRestful APIの特徴を持ち、HTTP APIはRestful APIの特徴を一部受け継いでいます。HTTP APIはAPI自体にキャッシュ機能を備えていないため、Restful APIの「キャッシュ可能」という制約を単体では満たすことができません。

Restful API（HTTP APIとREST API）

RESTアーキテクチャスタイル

Restful APIはRESTアーキテクチャスタイルを実装するAPIのことを示します。ちなみに、RESTアーキテクチャスタイルはネットワークシステムを構成・管理するためのガイドラインのことを示します。具体的にはこのガイドライン（RESTアーキテクチャスタイル）に則ると、システムは以下のような制約を満たさなければなりません。

  1. クライアント/サーバ：フロントエンドとバックエンドの処理がクライアントとサーバで分離している
  2. ステートレスサーバ ：クライアントとの過去のやり取りの状態をサーバが保持しない
  3. キャッシュ可能：サーバから取得したリソースをクライアントのローカルストレージに蓄積し、再利用できる
  4. 統一インターフェース：URIがHTTPメソッドによって取得されるように、統一的な様式でリソースの橋渡しが行われる
  5. 階層化システム：役割に応じて、システムを複数の階層に分離できる
  6. コードオンデマンド：クライアントはサーバから送信されたコードを処理できる（オプション）

API Gatewayで選択できる「HTTP API」と「REST API」では、これらの制約を満たすWeb APIを作成することができます。

HTTP APIとREST APIの違い

REST API は HTTP API よりも多くの機能をサポートしていますが、HTTP API は低価格で提供できるように最小限の機能で設計されています。

REST API と HTTP API のどちらかを選択するより引用

上記の引用文にあるように、REST API には様々な管理・開発機能が搭載されており、HTTP API は低価格で必要最低限の機能を備えています。

例えば、API Gateway において「REST API」を選択した場合に利用できる機能は以下があげられます。

  • VPC経由でしかアクセスできないAPIエンドポイントを作成すること。
  • サーバへのトラフィックを減少させるためにAPIがキャッシュを保持すること。
  • セキュリティ強化のためにAWS WAFと連携すること。
  • クライアントごとにAPIの使用量を調整・制御すること。

※その他の違いに関してはREST API と HTTP API のどちらかを選択するをご覧ください。

ただし、REST APIは様々な機能を搭載している分、HTTP APIに比べて料金は高くなります。実際、東京リージョンでの利用を想定すると、REST APIのAPIコールごとの料金はHTTP APIの約3.3倍です。そのため、どちらのAPIを使用するのかは案件の要件を踏まえて、慎重に検討する必要があります。

WebSocket API

WebSocketという通信プロトコル

WebSocketはWebSocketと呼ばれる通信プロトコルを用いることで、サーバとクライアント間で双方向接続を行います。 下記はWebSocket APIを用いた場合のAPIのエンドポイントの一例です。

wss://abcdef123.execute-api.ap-northeast-1.amazonaws.com/production/

Webブラウザでの検索などで見慣れたhttpやhttpsとは異なり、wssというプロトコルが含まれています。（対して、先ほど紹介したRestful APIではhttpsがプロトコルとして使用されます。）

対話的なやり取り

繰り返しになりますが、このプロトコルによる接続の特徴はサーバとクライアント間で双方向接続ができることです。

例えば、下記はAWSが公式で提供するWebSocket APIのハンズオンで作成したWebSocket APIの接続の様子です。wscat -cによってwss://abcdef123.execute-api.ap-northeast-1.amazonaws.com/production/に接続後、複数のやり取りが行われていることがわかります。

wscat -c wss://abcdef123.execute-api.ap-northeast-1.amazonaws.com/production/

Connected (press CTRL+C to quit)
> {"action": "sendmessage", "message": "hello, everyone!"}
< Hey!
> {"action": "sendmessage", "message": "What's up!"}
< good!

また、これらのメッセージのやり取りを実現するのは、接続が継続されている間（CTRL+Cでクライアントが切断するまで）、サーバがクライアントとの接続状態（コネクション）を管理・保持しているためです。この特徴は、RESTアーキテクチャスタイルで登場したステートレスとは対照的に、ステートフルといいます。よって、REST APIとHTTP APIはステートレスだが、WebSocket APIはステートフルとざっくり覚えておくといいでしょう。

料金

API Gatewayの利用料金は下記の通りです。
表の価格例は2025/10/19時点のap-northeast-1（東京リージョン）の料金を参照しております。

APIの種類 課金項目 価格例
REST API
  • 受信したAPIコール
  • 転送データ量
  • AWS PrivateLinkの料金（プライベートREST APIの場合）
  • キャッシュサイズ
 APIコール：4.25ドル（100万コールあたり）※注釈1
転送データ量：0.09ドル（1GBあたり）
キャッシュメモリ：メモリサイズに依存
HTTP API
  • 受信したAPIコール（月間3億以下と想定）
  • 転送データ量
 APIコール：1.29ドル（100万コールあたり）※注釈1
転送データ量：0.09ドル（1GBあたり）
WebSocket API
  • 送受信したメッセージ数
  • 分単位の接続合計時間
 メッセージ数：1.26ドル（100万あたり）※注釈2
接続合計時間：0.315ドル（100万分あたり）

※注釈1：APIコールは月間のリクエスト数が3億以下であることを想定しています。
※注釈2：WebSocketの月間メッセージ数は10億以下であると想定しています。

上記の表における価格例では、最も使用量が少なく料金が高いパターンを想定しています。そのため、使用量が増加し、料金ステージがアップした場合、より安い単価で利用できる可能性があります。（例えば、HTTP APIでは月間あたり3億以上のAPIコールがあった場合、100万コールあたりの料金は1.18ドルであり、それ以下の場合に比べて、0.11ドル安くなります。）

なお、詳しい料金体系に関しては公式ドキュメントを参考にしてください。

メリット

次に、API Gatewayを使用するメリットを簡単に紹介します。

1｜サーバレスでスケーラブル

メリットの一つ目はサーバレスなサービスであること、つまり、API Gatewayを管理・利用する上で利用者がサーバのことを意識する必要がないことです。そのため、開発担当者の利用・管理するための労力を削減することができます。また、API Gatewayはスケーラブルなサービスです。リソースの負荷に応じてその性能を増減させられるため、無駄なリソースを削減できます。

2｜セキュリティの導入しやすさ

API Gatewayには不正アクセスなどのセキュリティ上の脅威からサービスを保護するためのオプション機能が豊富に備わっています。例えば、JWT（JSON Web Token）オーソライザという機能によって、OpenID Connect (OIDC) や OAuth 2.0といった標準的なフレームワークを用いた認証・認可を導入できます。また、REST APIではAWSサービスの一つであるWAFと連携することで、ウェブアプリケーションファイアウォールを導入することができます。これらのサービスを駆使することで安全なAPIを構築できます。

3｜アクセス制限の機能

スロットリングと呼ばれる仕組みを活用することで、API Gatewayではクライアントからのリクエスト量に制限をかけることができます。この仕組みを利用すると「APIに対する全てのクライアントからのリクエスト数」や「クライアントごとのAPIに対するリクエスト数」を制限することができます。結果、過多なリクエストによって、APIとそのバックエンドのサーバに負担がかかることを防止できます。また、クライアントごとにリクエスト数の上限を設けることは、APIを収益源とするビジネスモデルの実現に役立ちます。

ハンズオンを通じて、API Gatewayを理解する

最後にハンズオンを通じて、API Gatewayの実践的な知識を整理していきます。

冒頭でAPI Gatewayでは、
・クライアントのリクエストをアプリサーバのどのような処理に結びつけるのか
・クライアントのリクエストをサーバが処理するために、リクエストをどのように翻訳するのか
設定する必要があると説明しました。そして、実際にこれらの設定を行うためにはAPI Gateway独自の設定項目の用語や具体的なデータ形式などを理解する必要があります。

そのため、ここでは、実際のAPI Gatewayを使用するアーキテクチャを対象に、API Gateway独自の設定項目の用語や具体的なデータ形式などを解説していきます。なお、API Gatewayを使用するアーキテクチャはAWSで提供されているチュートリアル: Lambda 非プロキシ統合を使用して REST API を作成するを参考に作成します。

目的と注意点

今回ハンズオンの目的はAPI Gatewayを使用するために必要な知識を身につけることです。そのため、ハンズオンの手順や証跡は省略しています。また、今回はチュートリアルに登場する設定や概念の説明に専念します。そのため、情報や説明が不足している部分もありますが、その点ご容赦ください。

扱うキーワード：
ステージ、リクエストパラメーター、メソッドリクエスト、統合リクエスト、マッピングテンプレート

構成図と挙動

上記の図が今回のハンズオンで作成するアーキテクチャです。
ハンズオンの手順に則って作成したAPIの振る舞いは以下です。

1｜クライアントがAPI エンドポイントに送信するリクエスト

curl POST \
  'https://j602e9jjj7.execute-api.ap-northeast-1.amazonaws.com/test/Seattle?time=evening' \
  -H 'content-type: application/json' \
  -H 'day: Thursday' \
  -H 'x-amz-docs-region: ap-northeast-1' \
  -d '{
    "callerName": "John"
}'

2｜APIエンドポイントからクライアントに返されるレスポンス

{"greeting":"Good evening, John of Seattle. Happy Thursday!"}

概説すると、このAPIは、クライアントから受け取った情報をもとに「greeting」、つまり、「挨拶」の文章を作成し、それをクライアントに返すAPIです。ちなみに、greetingの値は以下のように外部から与えられるデータによって決定します。

# {}は外部（クライアント）から渡されるデータによって決定する。
# {day}にあたるデータが外部（クライアント）から与えられれば「A」、与えられなければ「B」

A｜Good {time}, {name}, of {city}. Happy {day} !
B｜Good {time}, {name}, of {city}

重要な概念

それでは上記の挙動はどのような設定・仕組みによって実現しているのでしょうか。ここでは、それを把握するために重要となる概念を2つ取り上げます。

ステージ

ステージとはクライアントがデプロイされたREST APIのバージョンの識別子です。ステージを作成後、実際にユーザーがアクセスできるURL（APIエンドポイント）が発行されます。つまり、そのURLにリクエストメッセージを送信することで、目的の処理を API にリクエストすることができます。ステージ名は発行されるURLの一番右側に表示されます。

ステージ名「test」のURL

https://j602e9jjj7.execute-api.ap-northeast-1.amazonaws.com/test

ステージ「prod」のURL

https://j602e9jjj7.execute-api.ap-northeast-1.amazonaws.com/prod

ステージという単位で「APIをデプロイする環境」を区切るメリットは、開発の段階によって環境（作業場）を分けて管理できる点です。例えば、下記の画像のように開発環境を示すdev 、検証環境を示すstg、本番環境を示すprdなどで環境を区切ります。このようにすることで、互いに影響を与え合うことなく安全に、それぞれのフェーズで必要な作業を実施することができます。

リクエストパラメーター

リクエストパラメーターはクライアントがAPI に渡す実際のデータです。ここでいう「実際のデータ」は、「データに関する情報」であるメタデータではなく、APIの処理や動作に直接使用される情報そのもののことを指します。具体的には、API Gatewayでは以下の4つの受け渡し方が用意されています。（それぞれ例示されている箇所は今回のハンズオンから引用したものです。）

1｜パス（ 設定した場合、リクエストに必ず含まれていなければならない）

#「Seattle」部分
'https://j602e9jjj7.execute-api.ap-northeast-1.amazonaws.com/test/Seattle

2｜ヘッダー

 -H 'content-type: application/json' \
 -H 'day: Thursday' \

3｜クエリ文字列

#「time=evening」部分
'https://j602e9jjj7.execute-api.ap-northeast-1.amazonaws.com/test/Seattle?time=evening'

4｜ボディ

  -d '{
    "callerName": "John"
  }'

本記事では詳細を割愛しますが、どの方法でデータを受け渡すよう設計するべきかは、そのAPIが受け付けるリクエストメソッド（POSTやGETなど）や渡すデータそのものの意味合いによって異なります。ただし、リソースとして定義されたパスパラメーターをリクエストに含めることは必須だが、それ以外は基本的に含めるか否かは任意であるという点は、のちに紹介するメソッドリクエストの設定を理解する上で重要です。

API Gatewayのデータの流れと設定

いよいよAPI Gatewayの設定や仕組みについて触れていきます。API Gatewayでは、以下の4つの項目から2者間（クライアントとAPI GatewayやAPI GatewayとLambda）でのデータの受け渡しのルールやデータの変換の仕方を定義します。

コンソールの赤い箇所でどの2者間のデータを変換するのか選択します。

ここでは、今回のハンズオンで設定するメソッドリクエストと統合リクエストの解説を行います。

1｜メソッドリクエスト

関連するリクエスト（クライアントからAPIへのリクエスト）
リクエストライン:
POST https://j602e9jjj7.execute-api.ap-northeast-1.amazonaws.com/test/Seattle?time=evening

ヘッダー:
{
'User-Agent': 'python-requests/2.31.0', 
'Accept-Encoding': 'gzip, deflate, br, zstd', 
'Accept': '*/*', 
'Connection': 'keep-alive', 
'content-type': 'application/json', 
'day': 'Thursday', 
'x-amz-docs-region': 'ap-northeast-1', 
'Content-Length': '22'}

ボディ:
b'{"callerName": "John"}'
リクエストパラメーターの設定

メソッドリクエストではクライアントからどのようなリクエストパラメーターを受け取るのか設定します。

今回の場合は、受け取るパラメーターとして、以下を設定しています。

リクエストパス：cityの値（Seattleのこと）
クエリ文字列　：timeの値
ヘッダー　　　：dayの値

また、クエリ文字列とヘッダーには必須というオプションがありますが、これは「クライアントがそのパラメーターを含むことを強制するか否かを設定するもの」です。ちなみに、URLのパスの一部として配置されるパスパラメーターはこの場面では設定できません。そもそも、パスパラメーターは画像にあるようにリソース作成時に設定しており、設定した場合、リクエストに含めることは必須です。

メソッドリクエストの設定画面

パスパラメーターの設定（リソースの作成時）

※リクエストバリデーター
どの箇所のリクエストパラメーターに対して検証するのかを設定します。具体的には、リクエストが以下の条件を満たすか否か検証されます。

  • 受信リストの「必須」と設定したパラメーター（今回の場合、cityとtime）に値が含まれており、空白でない。
  • 該当するパラメーターが、メソッドで設定された特定のコンテンツタイプ（今回の場合はJSONスキーマー'content-type': 'application/json',）に準拠している。

この条件が満たされない場合、APIはクライアントに400エラーレスポンスを返し、リクエストは失敗します。

２｜統合リクエスト

統合リクエストが変換するデータ（APIからLambdaへ渡したeventオブジェクト）
{
'city': 'Seattle', 
'time': 'evening', 
'day': 'Thursday', 
'name': 'John'
}
HTTPリクエストからeventオブジェクトへのデータ変換

統合リクエストでは、(１)で紹介したリクエストをLambdaがデータを処理するためのeventオブジェクトに変換する設定を行います。ちなみにLambdaプロキシ統合ではLambdaが処理するためのデータ変換は自動で行われるため意識する必要はありません。しかし、今回はLambda非プロキシ統合であるため、マッピングテンプレートでデータの変換方式を指定する必要があります。

マッピングテンプレート
#set($inputRoot = $input.path('$'))
{
  "city": "$input.params('city')",
  "time": "$input.params('time')",
  "day":  "$input.params('day')",
  "name": "$inputRoot.callerName"
}

マッピングテンプレートは「VTL」と「JSON Path」を組み合わせて表現されます。

VTL：
正式名はVelocity Template Language。公式リファレンスでは「Webページに動的なコンテンツを組み込むための、最も簡単、シンプル、そしてクリーンな方法を提供することを目標とする」言語と紹介されている。

公式リファレンス：https://velocity.apache.org/engine/devel/vtl-reference.html

JSON Path：
JSONデータ（JavaScript Object Notation）内の特定の値を参照するためのクエリ言語。

今回と関連する解説

  • VTLでは変数を#set（変数名 = 代入する値）で定義する。
  • VTLでは単なる文字列と区別するために変数を参照する際は「$」をおく。
  • $input.pathと$input.paramsはAWSによって用意された変数である。
  • $input.pathは()で指定されたJSONオブジェクトを返す変数であり、括弧内の$はルートオブジェクトを表す。（よって、今回の場合、クライアントから受け取ったリクエストパラメーターをJSONオブジェクトで返す変数である。）
  • $input.paramsは()で指定されたパス、クエリ文字列、またはヘッダー値からリクエストパラメーターの値を返す。

以上の構文を用いることで、クライアントから与えられたリクエストパラメーターをLambdaが処理できるEventオブジェクトに変換します。

※マッピングテンプレートのデータ変換の詳しい説明はAPI Gateway のデータ変換の変数に記載されています。

まとめ

最後までお読みいただきありがとうございました。
本稿では、主に、API Gatewayの基本的な役割、3つのAPIタイプ（REST/HTTP/WebSocket）の特徴と違い、そして設定の核となる「メソッドリクエスト」と「統合リクエスト」について解説しました。本解説はAPI Gatewayの基本を凝縮したものですが、機能は多岐にわたります。さらに詳細な仕様や最新の情報については、Amazon API Gateway ドキュメントをご参照ください。