API Gateway（HTTP API v2）入門

概要

AWS の API Gateway には「REST API（v1）」と「HTTP API（v2）」の2系統があります。本記事では、後発で軽量な HTTP API（v2） を対象に、何が違うのか・どんなときに選ぶのか・最小構成の作り方・JWT 認可やルーティングの基本までを入門者向けに整理します。

先に結論を書くと、Lambda や HTTP バックエンドを薄く・安く・速く公開したいだけなら HTTP API（v2）が第一候補です。逆に、使用量プラン（API キー課金）や詳細なリクエスト／レスポンス変換、WAF 連携などが必要なら REST API（v1）を検討します。

なお本記事のコマンド・値はすべて例示です。アカウント ID・ARN・ドメインは 123456789012 や example.com のようなプレースホルダに置き換えています。

HTTP API（v2）とは

HTTP API は、HTTP バックエンド・Lambda 関数の公開に特化した軽量タイプです。REST API（v1）の機能をあえて絞り込み、代わりに次を得ています。

• 低コスト（REST API よりリクエスト単価が安い傾向）
• 低レイテンシ
• 設定がシンプル（デフォルトルート・自動デプロイなど）
• ネイティブな JWT オーソライザー（Cognito などの OIDC/OAuth2 プロバイダをコードなしで統合）
• CORS を設定だけで有効化

一方、以下は ない／弱い 点です（v1 を選ぶ判断材料）。

• API キー＋使用量プランによる従量課金・レート制限の個別配布
• リクエスト／レスポンスの本格的なマッピングテンプレート（VTL）
• WAF の統合（v1/v2 で対応状況が異なるため要確認）
• Edge-optimized エンドポイント（v2 はリージョナル中心）

REST API（v1）との比較

観点	HTTP API（v2）	REST API（v1）
主な用途	Lambda / HTTP の薄い公開	フル機能の API 管理
コスト	安い	高め
レイテンシ	低い	相対的に高い
JWT オーソライザー	ネイティブ対応	Lambda オーソライザーで実装
API キー / 使用量プラン	なし	あり
リクエスト変換（VTL）	限定的	充実
CORS	設定だけで有効化	要設定
ペイロード形式	v2.0（デフォルト）	v1.0

ペイロード形式（v1.0 と v2.0）の違い

HTTP API を Lambda プロキシ統合で使う場合、イベント／レスポンスの形が v1.0 と v2.0 で異なります。入門者が最初につまずくポイントです。

HTTP API のデフォルトは v2.0 で、HTTP メソッドやパスが requestContext.http 配下に入ります。

{
  "version": "2.0",
  "routeKey": "GET /items",
  "rawPath": "/items",
  "requestContext": {
    "http": {
      "method": "GET",
      "path": "/items",
      "sourceIp": "192.0.2.1"
    }
  },
  "body": null,
  "isBase64Encoded": false
}

レスポンスも簡略化でき、プレーンな JSON をそのまま return すると 200・JSON 扱いになります。

# Python (Lambda, payload format v2.0)
def handler(event, context):
    method = event["requestContext"]["http"]["method"]
    return {"message": f"hello from {method}"}  # dict を返すだけで 200 OK

ステータスやヘッダーを明示したい場合は従来形式でも返せます。

import json

def handler(event, context):
    return {
        "statusCode": 201,
        "headers": {"content-type": "application/json"},
        "body": json.dumps({"created": True}),
    }

v1.0（REST API 互換）の event["httpMethod"] や event["path"] は v2.0 イベントには存在しません。移行時はここで KeyError が頻発するので、requestContext.http.method への読み替えを最初に行ってください。

最小構成を作る（AWS CLI）

1. --target で一撃生成

aws apigatewayv2 create-api \
  --name "hello-http-api" \
  --protocol-type HTTP \
  --target "arn:aws:lambda:ap-northeast-1:123456789012:function:hello" \
  --region ap-northeast-1

--target に Lambda ARN を指定すると、デフォルトルート・ステージ・プロキシ統合・呼び出し権限までまとめて作成されます。返ってくる ApiEndpoint をそのまま叩けます。

curl https://abcdef123.execute-api.ap-northeast-1.amazonaws.com/

2. ルートを明示的に追加する

# 統合（Lambda プロキシ）
aws apigatewayv2 create-integration \
  --api-id abcdef123 \
  --integration-type AWS_PROXY \
  --integration-uri "arn:aws:lambda:ap-northeast-1:123456789012:function:hello" \
  --payload-format-version "2.0" \
  --region ap-northeast-1

# ルート（routeKey = "METHOD /path"）
aws apigatewayv2 create-route \
  --api-id abcdef123 \
  --route-key "GET /hello" \
  --target "integrations/INTEGRATION_ID" \
  --region ap-northeast-1

routeKey は "GET /hello" のように メソッドとパスを1文字列で表します。パスパラメータは "GET /items/{id}"、キャッチオールは "ANY /{proxy+}"、フォールバックは $default です。

3. Lambda へ呼び出し権限を付与する

--target を使わない場合は権限の明示が必要です。

aws lambda add-permission \
  --function-name hello \
  --statement-id apigw-invoke \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:ap-northeast-1:123456789012:abcdef123/*/*/hello" \
  --region ap-northeast-1

JWT オーソライザーでアクセス制御する

HTTP API の目玉が ネイティブ JWT オーソライザーです。Cognito ユーザープールや任意の OIDC プロバイダの JWT を、Lambda オーソライザーを書かずに検証できます。

aws apigatewayv2 create-authorizer \
  --api-id abcdef123 \
  --authorizer-type JWT \
  --name "cognito-jwt" \
  --identity-source '$request.header.Authorization' \
  --jwt-configuration \
    Audience="YOUR_APP_CLIENT_ID",Issuer="https://cognito-idp.ap-northeast-1.amazonaws.com/ap-northeast-1_xxxxxxxxx" \
  --region ap-northeast-1

ルートに紐づけると、有効な JWT がなければ 401。検証済みクレームは Lambda で参照できます。

def handler(event, context):
    claims = event["requestContext"]["authorizer"]["jwt"]["claims"]
    return {"user": claims["sub"], "email": claims.get("email")}

重要な注意点として、JWT オーソライザーが行うのは 署名・有効期限・issuer・audience の検証（＝認証）までです。「どのユーザーがどのデータにアクセスしてよいか」という 認可はアプリ側の責務です。認証が通っただけで全データを返さないよう、Lambda 内で所有者チェックを必ず入れてください。

CORS の有効化

aws apigatewayv2 update-api \
  --api-id abcdef123 \
  --cors-configuration \
    AllowOrigins="https://example.com",AllowMethods="GET,POST,OPTIONS",AllowHeaders="content-type,authorization" \
  --region ap-northeast-1

本番では AllowOrigins を * にせず、必要なオリジンだけを明示します。

確認方法

# 認可付きルート
curl -i https://abcdef123.execute-api.ap-northeast-1.amazonaws.com/secure            # 401 を期待
curl -i -H "Authorization: Bearer <JWT>" \
  https://abcdef123.execute-api.ap-northeast-1.amazonaws.com/secure                  # 200 を期待

アクセスログは aws apigatewayv2 update-stage --access-log-settings ... で CloudWatch Logs に出力できます。Lambda のログも合わせて確認しましょう。

注意点

• ペイロード形式 v2.0 を前提にコードを書く（httpMethod → requestContext.http.method）。
• API キー・使用量プランは非対応。利用者ごとの従量制限が要るなら v1。
• VTL による本格的な変換は不可。変換はアプリ側で行うか v1 を使う。
• WAF 等の統合は v1/v2 で対応状況が異なるため、要件があれば最新ドキュメントで確認する。
• 認証と認可を混同しない。前者は Gateway、後者はアプリの仕事。
• IaC（CDK / Terraform / SAM）では v1 と v2 でコンストラクト／リソースが別物なので取り違えに注意。

まとめ

• HTTP API（v2）は Lambda / HTTP を薄く安く速く公開するための軽量タイプ。
• --target を使えば 1コマンドで API が立つ手軽さ。
• ネイティブ JWT オーソライザーと設定だけの CORS が強力。
• API キー課金・VTL 変換が必要なら v1 を選ぶ。
• 最大の落とし穴は ペイロード形式 v2.0。ここさえ押さえれば入門は十分です。

「まず小さく公開して、足りなければ v1 を検討する」——この順番が HTTP API 入門の王道です。