api-gateway-http-api

API Gateway HTTP API (v2)

Overview

HTTP API (v2) is the recommended API Gateway type for most Lambda-backed APIs: lower cost, lower latency, and native JWT authorizers. Use payload format version 2.0 and type APIGatewayProxyEventV2 in handlers.

When to Use HTTP API vs REST API

Use HTTP API (v2)	Use REST API (v1)
New APIs, JWT/Cognito auth	API keys, request validation, WAF v1
Lower cost, simpler	Complex request/response mapping
Real estate web app (Cognito)	Legacy or specific v1 features

Dependencies

pnpm add -D @types/aws-lambda
# CDK: aws-cdk-lib (HttpApi, HttpLambdaIntegration, HttpJwtAuthorizer)

CDK HttpApi with JWT Authorizer

// cdk/lib/stacks/http-api-stack.ts

import { Stack, StackProps } from "aws-cdk-lib";
import { Construct } from "constructs";
import {
  HttpApi,
  HttpMethod,
  PayloadFormatVersion,
  HttpRouteKey,
} from "aws-cdk-lib/aws-apigatewayv2";
import { HttpLambdaIntegration } from "aws-cdk-lib/aws-apigatewayv2-integrations";
import { HttpJwtAuthorizer } from "aws-cdk-lib/aws-apigatewayv2-authorizers";
import { StandardLambda } from "../constructs/lambda-function";
import { Table } from "aws-cdk-lib/aws-dynamodb";

interface HttpApiStackProps extends StackProps {
  dataTable: Table;
  idempotencyTable: Table;
  userPoolId: string;
  userPoolClientId: string;
}

export class HttpApiStack extends Stack {
  public readonly httpApi: HttpApi;

  constructor(scope: Construct, id: string, props: HttpApiStackProps) {
    super(scope, id, props);

    const jwtAuthorizer = new HttpJwtAuthorizer("JwtAuthorizer", props.userPoolId, {
      identitySource: ["$request.header.Authorization"],
      jwtAudience: [props.userPoolClientId],
    });

    this.httpApi = new HttpApi(this, "RealEstateHttpApi", {
      apiName: "real-estate-http-api",
      corsPreflight: {
        allowOrigins: [process.env.CORS_ORIGIN ?? "https://app.example.com"],
        allowMethods: [HttpMethod.GET, HttpMethod.POST, HttpMethod.PUT, HttpMethod.DELETE],
        allowHeaders: ["Content-Type", "Authorization", "X-Correlation-Id"],
        allowCredentials: true,
      },
    });

    const getPropertyHandler = new StandardLambda(this, "GetProperty", {
      entry: "src/functions/get-property/handler.ts",
      handler: "handler",
      memorySize: 256,
      timeoutSeconds: 10,
      environment: { DYNAMODB_TABLE_NAME: props.dataTable.tableName },
    });
    props.dataTable.grantReadData(getPropertyHandler);

    // Public route (no auth)
    this.httpApi.addRoutes({
      path: "/properties/{propertyId}",
      methods: [HttpMethod.GET],
      integration: new HttpLambdaIntegration(
        "GetPropertyIntegration",
        getPropertyHandler,
        { payloadFormatVersion: PayloadFormatVersion.V2_0 }
      ),
    });

    // Protected route (JWT required)
    const createListingHandler = new StandardLambda(this, "CreateListing", {
      entry: "src/functions/create-listing/handler.ts",
      handler: "handler",
      memorySize: 512,
      timeoutSeconds: 30,
      environment: {
        DYNAMODB_TABLE_NAME: props.dataTable.tableName,
        IDEMPOTENCY_TABLE_NAME: props.idempotencyTable.tableName,
      },
    });
    props.dataTable.grantReadWriteData(createListingHandler);
    props.idempotencyTable.grantReadWriteData(createListingHandler);

    this.httpApi.addRoutes({
      path: "/listings",
      methods: [HttpMethod.POST],
      integration: new HttpLambdaIntegration(
        "CreateListingIntegration",
        createListingHandler,
        { payloadFormatVersion: PayloadFormatVersion.V2_0 }
      ),
      authorizer: jwtAuthorizer,
    });
  }
}