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

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,
    });
  }
}