Amazon API Gatewayの「HTTP API」へのマイグレーション #reinvent

Amazon API Gatewayの新機能「HTTP API」

re:Invent 2019期間中、Amazon API Gatewayの新機能「HTTP API」が発表されました。現在プレビューとして、US East (Ohio), US East (N. Virginia), US West (N. California), US West (Oregon), Asia Pacific (Sydney), Asia Pacific (Tokyo), EU (Frankfurt), EU (Ireland)で提供されています。

本記事では以下のドキュメントに記載されているHTTP APIへのマイグレーション方法を確認したいと思います。

• Migrating to an HTTP API - Amazon API Gateway

本記事はプレビュー版として公開されているドキュメントを参考にした考察です。本リリース時には仕様などが変わる可能性がありますのでご容赦ください。

OpenAPI 3.0の定義ファイルからインポート可能

HTTP APIはOpenAPI 3.0の定義ファイルからのインポートをサポートしています。REST APIからHTTP APIへのマイグレーションを行いたい場合は、構築済みのREST APIをOpenAPI 3.0形式の定義ファイルをエクスポートする必要があります。

REST APIのOpenAPI 3.0定義ファイルのエクスポート

REST APIのエクスポートは多機能で、様々なユースケースをサポートしています。OpenAPI 3.0定義ファイルのエクスポートももちろん手厚くサポートされています。

• Export a REST API from API Gateway - Amazon API Gateway

エンドポイントは以下のようになります。

https://<host>/restapis/<restapi_id>/stages/<stage_name>/exports/oas30

JSON形式でダウンロードしたい場合、以下のようにリクエストします。

$ curl -XGET https://<host>/restapis/<restapi_id>/stages/<stage_name>/exports/oas30 \
  -H 'Host: apigateway.<region>.amazonaws.com' \
  -H 'Accept: application/json'

インポート方法

インポート方法は簡単で、以下のようなCLIコマンドを実行するだけです。api-definition.json は前述しているエクスポートしたファイルを指定します。

$ aws apigatewayv2 import-api --body file://api-definition.json

インポートについての3つのバリデーション情報

インポートを行うと、APi Gatewayは3つのカテゴリのバリデーション情報を提供してくれます。

Info

PropertyはOpenAPIの仕様としては正しいですが、HTTP APIではサポートされていません。

たとえば次の例です。

"paths": {
  "/": {
    "get": {
      "x-amazon-apigateway-integration": {
        "type": "AWS_PROXY",
        "httpMethod": "POST",
        "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
        "payloadFormatVersion": "1.0"
      },
      "requestBody": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Body"
            }
          }
        }
      }
    }
  }
  ...
},
"components": {
  "schemas": {
    "Body": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string"
        }
      }
    }
    ...
  }
  ...
}

HTTP APIはリクエストのバリデーションをサポートしていないため、インポートに関する情報を生成します。API GatewayはrequestBodyおよびschemaフィールドを無視します。

Warning

OpenAPI仕様ではPropertyまたはStructureは無効ですが、APIの作成は行われます。インポート時にこれが検出された場合、これらの警告を無視してAPIの作成を続行するか、APIの作成を停止するかを指定できます。

"x-amazon-apigateway-integration": {
  "type": "AWS",
  "httpMethod": "POST",
  "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
  "payloadFormatVersion": "1.0"
}

Error

定義ドキュメントがOpenAPI仕様上が無効であるか、インポートの形式が正しくない場合、API Gatewayはリソースを作成できません。その場合はインポートが失敗するため、エラー内容を修正してから再試行する必要があります。

例えば次の例はOpenAPI 2.0仕様を使っていますが、HTTP APIはOpenAPI 3.0仕様のみをサポートするため、次のAPI定義はインポート時にエラーを生成します。

{
  "swagger": "2.0.0",
  "info": {
    "title": "My API",
    "description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo",
    "version": "1.0"
  }
  ...
}

まとめ

OpenAPI 3.0のおかげで、簡単にエクスポート/インポートが行えることが分かりました。移行を考えられている際はぜひ参考にしてください。