CDKでの aws_apigateway と aws_apigatewayv2 の違い

きっかけ

CDKでAPI Gatewayを作成しようとすると、aws_apigateway と aws_apigatewayv2 があることに気づいた。

aws_apigatewayとaws_apigatewayv2の違い

これらの違いは、使用できるAPIのタイプにあります。
CDKはCloudFormationの仕様に準拠しているため、詳しくはCloudFormationのドキュメントをご参照ください。

• aws_apigateway
  • REST API
• aws_apigatewayv2
  • HTTP API
  • WebSocket API

参考リンク:

• aws_apigateway
• aws_apigatewayv2

そういえばREST APIとHTTP APIの違いって何だっけ？

REST APIとHTTP APIは、どちらもRESTfulなAPIです。
公式ドキュメントによると、これらの使い分けに関しては以下のように説明されています。

API キー、クライアントごとのスロットリング、リクエストの検証、AWS WAF の統合、プライベート API エンドポイントなどの機能が必要な場合は、REST API を選択します。REST API に含まれる機能が必要ない場合は、HTTP API を選択します。
REST APIとHTTP APIの違い

これを踏まえると、どちらを選択すればよいかが明確になります。
以下に差分の例をいくつか挙げます。

エンドポイントタイプ

エンドポイントタイプ	REST API	HTTP API
エッジ最適化	○	×
リージョン別	○	○
プライベート	○	×

認証オプション

認証オプション	REST API	HTTP API
IAM	○	○
リソースポリシー	○	×
Amazon Cognito	○	○
Lambda オーソライザー	○	○
JWT	×	○

機能

機能	REST API	HTTP API
カスタムドメイン	○	○
API キー	○	×
クライアントごとのレート制限	○	×
クライアントごとの使用量調整	○	×

REST APIにできてHTTP APIにできないことがある一方で、HTTP APIにのみ可能なこともあります。
HTTP APIにできて、REST APIにはできないことは何でしょうか？

HTTP APIでだけできること

認証

• JSON ウェブトークン (JWT)
  HTTP APIでは、Lambda オーソライザーを使用してJWTを検証

JWT オーソライザーを使用したい場合は、HTTP APIを作成する必要があります。
https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html

開発

• 自動デプロイ

自動デプロイを有効にすると、API に対する変更が自動的にリリースされます。
https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/http-api-stages.html

ちなみにCDKでは、L2構築の際に自動的に有効になりました。

test-stack.ts

export class HelpMotherTasksStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // Lambda設定
    const testFunction = new NodejsFunction(this, 'TestFunction', {
      entry: 'src/lambda/index.ts',
      runtime: Runtime.NODEJS_20_X,
      timeout: Duration.seconds(30),
      handler: 'handler',
    }

    // API Gateway
    const api = new aws_apigatewayv2.HttpApi(this, 'TestAPI');
    const testFunctionIntegration = new HttpLambdaIntegration("TestFunctionIntegration", testFunction);
    api.addRoutes({
      path: '/test',
      methods: [aws_apigatewayv2.HttpMethod.POST],
      integration: bedrockFunctionIntegration
    });

統合

以下の2つを使用する場合は、HTTP APIの検討の余地がありそうです。

• Application Load Balancer とのプライベート統合
• AWS Cloud Map とのプライベート統合

まとめ

REST APIとHTTP APIには、それぞれ異なる特徴があるため、用途に応じて選択することが重要です。また、CDKを使用する際は、aws_apigatewayとaws_apigatewayv2の使い分けにも注意しましょう。