サイトアイコン IT & ライフハックブログ｜学びと実践のためのアイデア集

Amazon API Gateway設計ガイド：REST、HTTP、WebSocket APIの選び方とGCP、Azureとの違い

greeden
AWS API Gateway

AWS API Gateway

Amazon API Gatewayは、クライアントから届くAPIリクエストを受け、認証情報の検証、流量制御、ルーティング、ログ記録などを共通化するAWSのマネージドサービスです。

設計では機能を増やす前に、どのクライアントが何を呼ぶのか、入口とバックエンドのどちらに責任を置くのか、障害をどう検知するのかを決めます。

先に結論を示すと、一般的なHTTP APIではHTTP APIを候補にし、APIキー、クライアント別の流量制御、リクエスト検証、AWS WAF連携、プライベートAPIなどが必要ならREST APIを検討します。

APIフロントが担う役割

APIフロントとは、ブラウザ、モバイルアプリ、外部システムなどのクライアントと、Lambda、コンテナ、業務システムなどのバックエンドの間に置く共通の入口です。

Amazon API Gatewayは、公開URLの提供、リクエストのルーティング、認証情報の検証、レート制限、ログとメトリクスの出力、バックエンドとの統合を担えます。

バックエンドにはAWS Lambda、公開HTTPエンドポイント、AWSサービス、VPC内のロードバランサーなどを接続できます。

統合は、API Gatewayが受け取ったリクエストを、どのバックエンドへどの形式で渡すかを定める接続設定です。

入口を共通化すると、各バックエンドが同じ認証処理やログ形式を個別実装する重複を減らせます。

ただし、業務上の権限判定や入力値の意味までゲートウェイに集めると、設定が複雑になり、変更箇所も追いにくくなります。

REST、HTTP、WebSocket APIの選び方

Amazon API GatewayにはREST API、HTTP API、WebSocket APIがあり、同じ名称の設定項目がすべての種類に存在するわけではありません。

現在の機能差は、AWSのREST APIとHTTP APIの公式比較で設計時に確認してください。

Amazon API GatewayのAPIタイプを選ぶ基準
種類 向いている要件 選定時の確認点
HTTP API LambdaまたはHTTPバックエンドを、比較的少ない設定で公開したい APIキー、クライアント別の流量制御、キャッシュ、AWS WAF連携、プライベートAPIなど、REST API側にある機能が必要か
REST API 利用プラン、APIキー、リクエスト検証、キャッシュ、リソースポリシー、AWS WAF連携などを使いたい 追加機能が本当に必要か、設定と運用の複雑さを受け入れられるか
WebSocket API チャットやリアルタイム通知など、サービス側からクライアントへ送信したい $connect、$disconnect、メッセージ用ルート、接続状態の管理方法

WebSocket APIは双方向通信を扱い、クライアントからの要求を待たずにサービス側からデータを送れます。

用途と接続先は、WebSocket APIの公式ガイドで確認できます。

選び方を「新しいからHTTP API」「高機能だからREST API」と決めると、必要な制御が欠けるか、使わない設定を抱えます。

先に要件表を作り、必要な機能を満たす最小の種類を選ぶ方が、構築後の変更理由を説明しやすくなります。

ゲートウェイとバックエンドの責任境界

API Gatewayに置く処理は、複数のAPIやバックエンドに共通し、入口で判定できるものに寄せます。

APIフロントとバックエンドの役割分担
処理 置き場所の目安 理由
ルーティング、TLS終端、アクセスログ APIフロント 入口で統一しやすく、バックエンドの実装差を隠せるため
トークン形式の検証、IAMによる呼び出し制御 APIフロント バックエンドへ到達する前に不正な要求を減らせるため
注文を取消できるか、他人のデータを更新できるか バックエンド 業務データと現在の状態を見なければ判断できないため
複雑なデータ変換、複数サービスの集約 原則としてバックエンドまたはBFF コードとしてテストし、変更履歴と責任を追いやすくするため

BFF（Backend for Frontend）は、Web、モバイル、外部パートナーなど、クライアントごとに必要なデータや操作をまとめるバックエンドです。

API GatewayはBFFへの入口とルーティングを担えますが、複数サービスを呼び出してレスポンスを組み立てる処理まで、必ずゲートウェイ設定に入れる必要はありません。

認証、認可、APIキーを分けて考える

認証は利用者やアプリの身元を確かめる処理で、認可は認証済みの主体に許された操作を判定する処理です。

サーバー間通信ではIAM、ユーザー向けAPIではCognitoなどが発行するJWT、独自要件がある場合はLambdaオーソライザーが候補になります。

どの方式でも、API Gatewayでトークンを検証しただけで業務上の認可が完了するとは限りません。

たとえば「ログイン済みである」は入口で確認できますが、「この注文を更新できる」は注文の所有者や状態を知るバックエンドで判定します。

APIキーは利用者を安全に認証する資格情報として扱わず、REST APIの利用プランでクライアントを識別し、使用量を集計する用途に限定します。

AWSもAPIキーと使用量プランの公式ガイドで、APIキーを認証や認可に使わないよう案内しています。

IAMと権限設計の全体像は、サイト内のAWS IAMの基礎と権限設計でも整理しています。

公開範囲と防御を重ねる

APIの防御は、認証方式だけで完結しません。

REST APIとHTTP APIでは対応する防御機能が異なるため、APIタイプを決める前に公開範囲と脅威を整理します。

VPC、サブネット、経路、公開境界の考え方は、Amazon VPC設計ガイドが補足になります。

流量制御、キャッシュ、可観測性

スロットリングは防波堤であり、請求額の上限ではない

スロットリングは、一定時間に受け付けるリクエスト数を調整し、急増した負荷からバックエンドを守る仕組みです。

REST APIの使用量プランではAPIキーごとのレートとクォータを設定できますが、AWSはこれらをベストエフォートと説明しています。

そのため、クォータだけをアクセス遮断やコスト上限として頼らず、予算監視、アラーム、防御ルール、バックエンド側の保護も組み合わせます。

キャッシュは更新条件から設計する

REST APIのステージキャッシュは、参照が多く更新頻度が低いレスポンスでバックエンド負荷を減らせます。

ただし、利用者や権限で結果が変わるAPIでは、キャッシュキーを誤ると別の利用者向けデータを返す危険があります。

何をキーにするか、いつ無効化するか、どのデータをキャッシュしないかを先に決めます。

HTTP APIにはREST APIと同じキャッシュ機能がないため、必要に応じてCloudFront、バックエンド、クライアントのキャッシュを検討します。

ログは調査手順とセットにする

アクセスログには、追跡に使うリクエストID、ルート、ステータスコード、処理時間などを構造化して残します。

4xxと5xxを分け、API Gatewayで拒否したのか、統合先が失敗したのかを判別できる形にします。

メトリクスを保存するだけでは障害対応につながらないため、監視対象、しきい値、通知先、最初に確認するダッシュボードを運用手順に含めます。

CloudWatchのメトリクス、ログ、アラームを設計する順序は、Amazon CloudWatch設計ガイドで詳しく説明しています。

代表的な構成パターン

Lambdaを使うサーバーレスAPI

HTTP APIまたはREST APIからLambdaを呼び出し、データストアや他のAWSサービスへ接続する構成です。

小さく始めやすい一方、同期リクエストの中に長時間処理を入れず、必要ならキューやワークフローへ分離します。

実行モデルと運用上の判断軸は、AWS Lambdaと他クラウドの比較も参考になります。

コンテナ基盤を非公開で接続するAPI

API GatewayからVPCリンクを経由し、ロードバランサーの背後にあるECSやEKSへ接続する構成です。

入口をAPI Gatewayに集めながら、既存のコンテナ運用とアプリケーション実装を活かせます。

コンテナの実行単位やEKSとの違いは、Amazon ECSの設計ガイドで確認できます。

クライアント別のBFF

Web、モバイル、パートナー向けに入口やルートを分け、それぞれのBFFへ接続する構成です。

レスポンス形式や認可条件が明確に異なる場合に有効ですが、名前だけ分けて同じ処理を複製すると保守箇所が増えます。

共通処理とクライアント固有処理の境界を設計書に残します。

Google Cloud、Azureとの違い

三つのクラウドにはAPIの入口を管理するサービスがありますが、同じ機能を同じ単位で提供しているわけではありません。

AWS、Google Cloud、AzureのAPI管理サービス比較
サービス 位置づけ 選定の軸
Amazon API Gateway REST、HTTP、WebSocket APIを公開し、AWSサービスやHTTPバックエンドと統合する 必要なAPIタイプとAWS固有機能、REST APIとHTTP APIの機能差
Google Cloud API Gateway OpenAPI定義をもとにAPIを配備し、認証、監視、バックエンド接続を管理する Cloud Run、Cloud Run functionsなどの既存バックエンドと、必要なAPI定義方式
Cloud Endpoints ESPまたはESPv2という分散プロキシをバックエンド前段で動かすAPI管理システム OpenAPIまたはgRPC、プロキシを置く実行環境、既存構成との整合
Azure API Management APIゲートウェイに加え、管理プレーンと開発者ポータルを含むAPI管理基盤 ポリシー、製品とサブスクリプション、開発者向け公開、組織的なガバナンス

Google Cloud API GatewayとCloud Endpointsは、どちらもAPI管理に使えますが、前者はゲートウェイとして配備し、後者はESPまたはESPv2を使う分散型の構成です。

Google CloudのAPI Gateway公式ドキュメントとCloud Endpoints公式ドキュメントを分けて確認すると、構成の違いを判断しやすくなります。

Azure API Managementは、入口の転送だけでなく、APIの管理、ポリシー、開発者向けの発見と利用開始まで扱う点に特徴があります。

対応する構成要素は、Azure API Management公式ドキュメントで確認できます。

設計を決める手順

  1. 利用者と通信方式を列挙する
    ブラウザ、モバイル、サーバー間、外部パートナーを分け、HTTPと双方向通信のどちらが必要かを整理します。
  2. 公開範囲を決める
    インターネット公開、社内限定、VPC内限定を分け、接続元と経路を図にします。
  3. 認証と認可を分ける
    誰であるかを何で検証し、どの操作を許すかをどこで判定するかを記録します。
  4. 共通処理の置き場所を決める
    ルーティング、流量制御、変換、ログ、業務ルールを、APIフロントとバックエンドに割り当てます。
  5. 必要機能からAPIタイプを選ぶ
    HTTP APIで満たせない要件を明示し、REST APIを選ぶ理由を残します。
  6. 障害時の観測方法を決める
    リクエストID、ログ、メトリクス、アラーム、担当者の調査手順を用意します。
  7. 小さな経路で検証する
    代表的な1本のAPIで認証、エラー、負荷、ログ、デプロイとロールバックを確認します。

よくある設計ミス

高機能な種類を先に選ぶ

REST APIの機能を使う予定がないのに採用すると、設定項目と運用判断だけが増えます。

必要機能の一覧を作り、HTTP APIで不足する項目を採用理由にします。

APIキーをログイン情報として使う

APIキーは認証や認可の代わりになりません。

IAM、JWT、Lambdaオーソライザーなどで主体を検証し、業務上の認可はバックエンドでも行います。

ゲートウェイへ業務ロジックを集める

複雑なマッピングや条件分岐を設定へ詰め込むと、テストとレビューが難しくなります。

入口で共通化する処理と、コードで管理する業務処理を分けます。

ログを出すだけで運用を終える

ログの保存先があっても、通知条件と調査手順がなければ復旧は早まりません。

障害の種類ごとに、誰が何を見て判断するかまで決めます。

同期APIで長時間処理を完了させる

時間のかかる処理はタイムアウトと再試行の影響を受けやすいため、要求を受け付けた後にキューやワークフローへ渡す非同期化を検討します。

導入前チェックリスト

APIフロント設計の結論

Amazon API Gatewayは、APIの入口で共通の制御と観測をそろえ、バックエンドの実装をクライアントから分離するためのサービスです。

HTTP API、REST API、WebSocket APIの選択は、機能の多さではなく、通信方式、公開範囲、認証、流量制御、キャッシュ、運用に必要な機能から決めます。

最初の実務は、既存APIを1本選び、クライアントからバックエンドまでの経路と、各層が負う責任を書き出すことです。

その図と要件表があれば、AWS、Google Cloud、Azureのどのサービスを使う場合でも、製品名に引っ張られずに設計を比較できます。

参考にした公式情報

この記事に関連する株式会社greedenの取り組み

APIの入口設計では、認証や監視を後付けせず、要件定義から運用まで一貫して決める必要があります。株式会社greedenは、API開発やAWSを含むクラウド構築、リリース後の保守改善まで、Webシステム開発を継続して支援します。

モバイルバージョンを終了