FastAPI

FastAPI is a framework for building APIs in Python.

The FastAPI generator creates a new FastAPI with AWS CDK or Terraform infrastructure setup. The generated backend uses AWS Lambda for serverless deployment, exposed via an AWS API Gateway API. It sets up AWS Lambda Powertools for observability, including logging, AWS X-Ray tracing and Cloudwatch Metrics.

Usage

Generate a FastAPI

You can generate a new FastAPI in two ways:

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - py#fast-api
5. Fill in the required parameters
6. Click Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#fast-api

yarn

yarn nx g @aws/nx-plugin:py#fast-api

npm

npx nx g @aws/nx-plugin:py#fast-api

bun

bunx nx g @aws/nx-plugin:py#fast-api

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:py#fast-api --dry-run

yarn

yarn nx g @aws/nx-plugin:py#fast-api --dry-run

npm

npx nx g @aws/nx-plugin:py#fast-api --dry-run

bun

bunx nx g @aws/nx-plugin:py#fast-api --dry-run

Options

Parameter	Type	Default	Description
name Required	string	-	Name of the API project to generate
computeType	string	ServerlessApiGatewayRestApi	The type of compute to use to deploy this API. Choose between ServerlessApiGatewayRestApi (default) or ServerlessApiGatewayHttpApi.
auth	string	IAM	The method used to authenticate with your API. Choose between IAM (default), Cognito or None.
directory	string	packages	The directory to store the application in.
iacProvider	string	CDK	The preferred IaC provider
moduleName	string	-	Python module name

Note

You can choose between either a REST API or HTTP API to deploy your API, please refer to the API Gateway Developer Guide to help you decide.

Generator Output

The generator will create the following project structure in the <directory>/<api-name> directory:

• project.json Project configuration and build targets
• pyproject.toml Python project configuration and dependencies
• Directory<module_name>

  • __init__.py Module initialisation
  • init.py Sets the up FastAPI app and configures powertools middleware
  • main.py API implementation
• Directoryscripts

  • generate_open_api.py Script to generate an OpenAPI schema from the FastAPI app

Infrastructure

Since this generator vends infrastructure as code based on your chosen iacProvider, it will create a project in packages/common which includes the relevant CDK constructs or Terraform modules.

The common infrastructure as code project is structured as follows:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Note

This project is generated using the ts#project generator and therefore configures the same build targets.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Note

This project is generated using the terraform#project generator and therefore configures the same build targets.

For deploying your API, the following files are generated:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directoryapis

      • <project-name>.ts CDK construct for deploying your API
  • Directorycore

    • Directoryapi

      • http-api.ts CDK construct for deploying an HTTP API (if you selected to deploy an HTTP API)
      • rest-api.ts CDK construct for deploying a REST API (if you selected to deploy a REST API)
      • utils.ts Utilities for the API constructs

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directoryapis

      • Directory<project-name>

        • <project-name>.tf Module for deploying your API
  • Directorycore

    • Directoryapi

      • Directoryhttp-api

        • http-api.tf Module for deploying an HTTP API (if you selected to deploy an HTTP API)
      • Directoryrest-api

        • rest-api.tf Module for deploying a REST API (if you selected to deploy a REST API)

Implementing your FastAPI

The main API implementation is in main.py. This is where you define your API routes and their implementations. Here’s an example:

from .init import app, tracer
from pydantic import BaseModel

class Item(BaseModel):
  name: str

@app.get("/items/{item_id}")
def get_item(item_id: int) -> Item:
    return Item(name=...)

@app.post("/items")
def create_item(item: Item):
    return ...

The generator sets up several features automatically:

1. AWS Lambda Powertools integration for observability
2. Error handling middleware
3. Request/response correlation
4. Metrics collection
5. AWS Lambda handler using Mangum

Observability with AWS Lambda Powertools

Logging

The generator configures structured logging using AWS Lambda Powertools. You can access the logger in your route handlers:

from .init import app, logger

@app.get("/items/{item_id}")
def read_item(item_id: int):
    logger.info("Fetching item", extra={"item_id": item_id})
    return {"item_id": item_id}

The logger automatically includes:

• Correlation IDs for request tracing
• Request path and method
• Lambda context information
• Cold start indicators

Tracing

AWS X-Ray tracing is configured automatically. You can add custom subsegments to your traces:

from .init import app, tracer

@app.get("/items/{item_id}")
@tracer.capture_method
def read_item(item_id: int):
    # Creates a new subsegment
    with tracer.provider.in_subsegment("fetch-item-details"):
        # Your logic here
        return {"item_id": item_id}

Metrics

CloudWatch metrics are collected automatically for each request. You can add custom metrics:

from .init import app, metrics
from aws_lambda_powertools.metrics import MetricUnit

@app.get("/items/{item_id}")
def read_item(item_id: int):
    metrics.add_metric(name="ItemViewed", unit=MetricUnit.Count, value=1)
    return {"item_id": item_id}

Default metrics include:

• Request counts
• Success/failure counts
• Cold start metrics
• Per-route metrics

Error Handling

The generator includes comprehensive error handling:

from fastapi import HTTPException

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id < 0:
        raise HTTPException(status_code=400, detail="Item ID must be positive")
    return {"item_id": item_id}

Unhandled exceptions are caught by the middleware and:

1. Log the full exception with stack trace
2. Record a failure metric
3. Return a safe 500 response to the client
4. Preserve the correlation ID

Tip

It’s recommended to specify response models for your API operations for better code generation if using the api-connection generator. See here for more details.

Streaming

With FastAPI, you can stream a response to the caller with the StreamingResponse response type.

Infrastructure Changes

Since AWS API Gateway does not support streaming responses, you will need to deploy your FastAPI to a platform which supports this. The simplest option is to use an AWS Lambda Function URL.

CDK

To achieve this, you can replace the generated common/constructs/src/app/apis/<name>-api.ts construct with one that deploys a function URL instead.

Example Streaming FunctionURL Construct

import { Duration, Stack, CfnOutput } from 'aws-cdk-lib';
import { IGrantable, Grant } from 'aws-cdk-lib/aws-iam';
import {
  Runtime,
  Code,
  Tracing,
  LayerVersion,
  FunctionUrlAuthType,
  InvokeMode,
  Function,
} from 'aws-cdk-lib/aws-lambda';
import { Construct } from 'constructs';
import url from 'url';
import { RuntimeConfig } from '../../core/runtime-config.js';

export class MyApi extends Construct {
  public readonly handler: Function;

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

    this.handler = new Function(this, 'Handler', {
      runtime: Runtime.PYTHON_3_12,
      handler: 'run.sh',
      code: Code.fromAsset(
        url.fileURLToPath(
          new URL(
            '../../../../../../dist/packages/my_api/bundle',
            import.meta.url,
          ),
        ),
      ),
      timeout: Duration.seconds(30),
      tracing: Tracing.ACTIVE,
      environment: {
        AWS_CONNECTION_REUSE_ENABLED: '1',
      },
    });

    const stack = Stack.of(this);
    this.handler.addLayers(
      LayerVersion.fromLayerVersionArn(
        this,
        'LWALayer',
        `arn:aws:lambda:${stack.region}:753240598075:layer:LambdaAdapterLayerX86:24`,
      ),
    );
    this.handler.addEnvironment('PORT', '8000');
    this.handler.addEnvironment('AWS_LWA_INVOKE_MODE', 'response_stream');
    this.handler.addEnvironment('AWS_LAMBDA_EXEC_WRAPPER', '/opt/bootstrap');
    const functionUrl = this.handler.addFunctionUrl({
      authType: FunctionUrlAuthType.AWS_IAM,
      invokeMode: InvokeMode.RESPONSE_STREAM,
      cors: {
        allowedOrigins: ['*'],
        allowedHeaders: [
          'authorization',
          'content-type',
          'x-amz-content-sha256',
          'x-amz-date',
          'x-amz-security-token',
        ],
      },
    });

    new CfnOutput(this, 'MyApiUrl', { value: functionUrl.url });

    // Register the API URL in runtime configuration for client discovery
    RuntimeConfig.ensure(this).config.apis = {
      ...RuntimeConfig.ensure(this).config.apis!,
      MyApi: functionUrl.url,
    };
  }

  public grantInvokeAccess(grantee: IGrantable) {
    Grant.addToPrincipal({
      grantee,
      actions: ['lambda:InvokeFunctionUrl'],
      resourceArns: [this.handler.functionArn],
      conditions: {
        StringEquals: {
          'lambda:FunctionUrlAuthType': 'AWS_IAM',
        },
      },
    });
  }
}

Terraform

To achieve this with Terraform, you can replace the generated API Gateway infrastructure with a Lambda Function URL that supports response streaming.

Example Streaming Lambda Function URL Configuration

# Data sources for current AWS context
data "aws_caller_identity" "current" {}
data "aws_region" "current" {}

# Lambda function for streaming FastAPI
resource "aws_lambda_function" "my_api_handler" {
  filename         = "../../../../../../dist/packages/my_api/bundle.zip"
  function_name    = "my-api-handler"
  role            = aws_iam_role.lambda_execution_role.arn
  handler         = "run.sh"
  runtime         = "python3.12"
  timeout         = 30
  source_code_hash = filebase64sha256("../../../../../../dist/packages/my_api/bundle.zip")

  # Enable X-Ray tracing
  tracing_config {
    mode = "Active"
  }

  # Environment variables for Lambda Web Adapter
  environment {
    variables = {
      AWS_CONNECTION_REUSE_ENABLED = "1"
      PORT                        = "8000"
      AWS_LWA_INVOKE_MODE        = "response_stream"
      AWS_LAMBDA_EXEC_WRAPPER    = "/opt/bootstrap"
    }
  }

  # Add Lambda Web Adapter layer
  layers = [
    "arn:aws:lambda:${data.aws_region.current.name}:753240598075:layer:LambdaAdapterLayerX86:24"
  ]

  depends_on = [
    aws_iam_role_policy_attachment.lambda_logs,
    aws_cloudwatch_log_group.lambda_logs,
  ]
}

# CloudWatch Log Group for Lambda function
resource "aws_cloudwatch_log_group" "lambda_logs" {
  name              = "/aws/lambda/my-api-handler"
  retention_in_days = 14
}

# IAM role for Lambda execution
resource "aws_iam_role" "lambda_execution_role" {
  name = "my-api-lambda-execution-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Action = "sts:AssumeRole"
        Effect = "Allow"
        Principal = {
          Service = "lambda.amazonaws.com"
        }
      }
    ]
  })
}

# Attach basic execution policy
resource "aws_iam_role_policy_attachment" "lambda_logs" {
  role       = aws_iam_role.lambda_execution_role.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
}

# Attach X-Ray tracing policy
resource "aws_iam_role_policy_attachment" "lambda_xray" {
  role       = aws_iam_role.lambda_execution_role.name
  policy_arn = "arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess"
}

# Lambda Function URL with streaming support
resource "aws_lambda_function_url" "my_api_url" {
  function_name      = aws_lambda_function.my_api_handler.function_name
  authorization_type = "AWS_IAM"
  invoke_mode       = "RESPONSE_STREAM"

  cors {
    allow_credentials = false
    allow_origins     = ["*"]
    allow_methods     = ["*"]
    allow_headers = [
      "authorization",
      "content-type",
      "x-amz-content-sha256",
      "x-amz-date",
      "x-amz-security-token"
    ]
    expose_headers = ["date", "keep-alive"]
    max_age       = 86400
  }
}

# Output the Function URL
output "my_api_url" {
  description = "URL for the streaming FastAPI Lambda Function"
  value       = aws_lambda_function_url.my_api_url.function_url
}

# Optional: Create SSM parameter for runtime configuration
resource "aws_ssm_parameter" "my_api_url" {
  name  = "/runtime-config/apis/MyApi"
  type  = "String"
  value = aws_lambda_function_url.my_api_url.function_url

  tags = {
    Environment = "production"
    Service     = "my-api"
  }
}

# IAM policy for granting invoke access to the Function URL
resource "aws_iam_policy" "my_api_invoke_policy" {
  name        = "my-api-invoke-policy"
  description = "Policy to allow invoking the streaming FastAPI Lambda Function URL"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = "lambda:InvokeFunctionUrl"
        Resource = aws_lambda_function.my_api_handler.arn
        Condition = {
          StringEquals = {
            "lambda:FunctionUrlAuthType" = "AWS_IAM"
          }
        }
      }
    ]
  })
}

# Example: Attach the invoke policy to a role (uncomment and modify as needed)
# resource "aws_iam_role_policy_attachment" "my_api_invoke_access" {
#   role       = var.authenticated_role_name
#   policy_arn = aws_iam_policy.my_api_invoke_policy.arn
# }

Note

For an end-to-end example, please refer to the Dungeon Adventure Tutorial

Implementation

Once you’ve updated the infrastructure to support streaming, you can implement a streaming API in FastAPI. The API should:

• Return a StreamingResponse
• Declare the return type of each response chunk
• Add the OpenAPI vendor extension x-streaming: true if you intend to use the API Connection.

For example, if you would like to stream a series of JSON objects from your API, you can implement this as follows:

from pydantic import BaseModel
from fastapi.responses import StreamingResponse

class Chunk(BaseModel):
  message: str
  timestamp: datetime

async def stream_chunks():
  for i in range(0, 100):
    yield Chunk(message=f"This is chunk {i}", timestamp=datetime.now())

@app.get("/stream", openapi_extra={'x-streaming': True})
def my_stream() -> Chunk:
    return StreamingResponse(stream_chunks(), media_type="application/json")

Consumption

To consume a stream of responses, you can make use of the API Connection Generator which will provide a type-safe method for iterating over your streamed chunks.

Deploying your FastAPI

The FastAPI generator creates CDK or Terraform infrastructure as code based on your selected iacProvider. You can use this to deploy your FastAPI.

CDK

The CDK construct for deploying your API in the common/constructs folder. You can use this in a CDK application:

import { MyApi } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the api to your stack
    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

This sets up:

1. An AWS Lambda function for each operation in the FastAPI application
2. API Gateway HTTP/REST API as the function trigger
3. IAM roles and permissions
4. CloudWatch log group
5. X-Ray tracing configuration
6. CloudWatch metrics namespace

Note

If you selected to use Cognito authentication, you will need to supply the identity property to the API construct:

import { MyApi, UserIdentity } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
      identity,
    });
  }
}

The UserIdentity construct can be generated using the ts#react-website-auth generator

Terraform

The Terraform modules for deploying your API are in the common/terraform folder. You can use this in a Terraform configuration:

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  # Environment variables for the Lambda function
  env = {
    ENVIRONMENT = var.environment
    LOG_LEVEL   = "INFO"
  }

  # Additional IAM policies if needed
  additional_iam_policy_statements = [
    # Add any additional permissions your API needs
  ]

  tags = local.common_tags
}

This sets up:

1. An AWS Lambda function that serves all FastAPI routes
2. API Gateway HTTP/REST API as the function trigger
3. IAM roles and permissions
4. CloudWatch log group
5. X-Ray tracing configuration
6. CORS configuration

Note

If you selected to use Cognito authentication, you will need to supply the Cognito configuration:

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  user_pool_id         = local.user_pool_id
  user_pool_client_ids = [local.client_id]

  env = {
    ENVIRONMENT = var.environment
    LOG_LEVEL   = "INFO"
  }

  tags = local.common_tags
}

You can set up Cognito User Pool and Client using the appropriate Terraform resources or modules.

The Terraform module provides several outputs you can use:

# Access the API endpoint
output "api_url" {
  value = module.my_api.stage_invoke_url
}

# Access Lambda function details
output "lambda_function_name" {
  value = module.my_api.lambda_function_name
}

# Access IAM role for granting additional permissions
output "lambda_execution_role_arn" {
  value = module.my_api.lambda_execution_role_arn
}

You can customize CORS settings by passing variables to the module:

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  # Custom CORS configuration
  cors_allow_origins = ["https://myapp.com", "https://staging.myapp.com"]
  cors_allow_methods = ["GET", "POST", "PUT", "DELETE"]
  cors_allow_headers = [
    "authorization",
    "content-type",
    "x-custom-header"
  ]

  tags = local.common_tags
}

Caution

If you selected None for auth when running the generator, you may see Checkov check failures such as:

HTTP API

Check: CKV_AWS_309: "Ensure API GatewayV2 routes specify an authorization type"
 FAILED for resource: aws_apigatewayv2_route.proxy_routes["PUT"]

REST API

Check: CKV_AWS_59: "Ensure there is no open access to back-end resources through API"
 FAILED for resource: aws_api_gateway_method.proxy_method

You can add a suppression comment if you are sure you wish for your API to be public.

Integrations

The REST/HTTP API CDK constructs are configured to provide a type-safe interface for defining integrations for each of your operations.

CDK

The CDK constructs provide full type-safe integration support as described below.

Terraform

Note

Terraform modules use the “router pattern” with a single Lambda function serving all operations. Type-safe integrations are not supported - the module creates one Lambda function that handles all API requests.

For explicit per-operation integrations with Terraform, you would need to manually create individual Lambda functions and API Gateway routes. See the Explicit Integrations section for examples.

Default Integrations

CDK

You can use the static defaultIntegrations to make use of the default pattern, which defines an individual AWS Lambda function for each operation:

new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this).build(),
});

Terraform

Terraform modules automatically use the router pattern with a single Lambda function. No additional configuration is needed:

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  # The module automatically creates a single Lambda function
  # that handles all API operations
  tags = local.common_tags
}

Accessing Integrations

CDK

You can access the underlying AWS Lambda functions via the API construct’s integrations property, in a type-safe manner. For example, if your API defines an operation named sayHello and you need to add some permissions to this function, you can do so as follows:

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this).build(),
});

// sayHello is typed to the operations defined in your API
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
  effect: Effect.ALLOW,
  actions: [...],
  resources: [...],
}));

Terraform

With Terraform’s router pattern, there’s only one Lambda function. You can access it via the module outputs:

# Grant additional permissions to the single Lambda function
resource "aws_iam_role_policy" "additional_permissions" {
  name = "additional-api-permissions"
  role = module.my_api.lambda_execution_role_name

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = [
          "s3:GetObject",
          "s3:PutObject"
        ]
        Resource = "arn:aws:s3:::my-bucket/*"
      }
    ]
  })
}

Customising Default Options

CDK

If you would like to customise the options used when creating the Lambda function for each default integration, you can use the withDefaultOptions method. For example, if you would like all of your Lambda functions to reside in a Vpc:

const vpc = new Vpc(this, 'Vpc', ...);

new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withDefaultOptions({
      vpc,
    })
    .build(),
});

Terraform

To customize options like VPC configuration, you need to edit the generated Terraform module. For example, to add VPC support to all Lambda functions:

packages/common/terraform/src/app/apis/my-api/my-api.tf

# Add VPC variables
variable "vpc_subnet_ids" {
  description = "List of VPC subnet IDs for Lambda function"
  type        = list(string)
  default     = []
}

variable "vpc_security_group_ids" {
  description = "List of VPC security group IDs for Lambda function"
  type        = list(string)
  default     = []
}

# Update the Lambda function resource
resource "aws_lambda_function" "api_lambda" {
  # ... existing configuration ...

  # Add VPC configuration
  vpc_config {
    subnet_ids         = var.vpc_subnet_ids
    security_group_ids = var.vpc_security_group_ids
  }
}

Then use the module with VPC configuration:

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  # VPC configuration
  vpc_subnet_ids         = [aws_subnet.private_a.id, aws_subnet.private_b.id]
  vpc_security_group_ids = [aws_security_group.lambda_sg.id]

  tags = local.common_tags
}

Overriding Integrations

CDK

You can also override integrations for specific operations using the withOverrides method. Each override must specify an integration property which is typed to the appropriate CDK integration construct for the HTTP or REST API. The withOverrides method is also type-safe. For example, if you would like to override a getDocumentation API to point to documentation hosted by some external website you could achieve this as follows:

new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOverrides({
      getDocumentation: {
        integration: new HttpIntegration('https://example.com/documentation'),
      },
    })
    .build(),
});

You will also notice that the overridden integration no longer has a handler property when accessing it via api.integrations.getDocumentation.

You can add additional properties to an integration which will also be typed accordingly, allowing for other types of integration to be abstracted but remain type-safe, for example if you have created an S3 integration for a REST API and later wish to reference the bucket for a particular operation, you can do so as follows:

const storageBucket = new Bucket(this, 'Bucket', { ... });

const apiGatewayRole = new Role(this, 'ApiGatewayS3Role', {
  assumedBy: new ServicePrincipal('apigateway.amazonaws.com'),
});

storageBucket.grantRead(apiGatewayRole);

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOverrides({
      getFile: {
        bucket: storageBucket,
        integration: new AwsIntegration({
          service: 's3',
          integrationHttpMethod: 'GET',
          path: `${storageBucket.bucketName}/{fileName}`,
          options: {
            credentialsRole: apiGatewayRole,
            requestParameters: {
              'integration.request.path.fileName': 'method.request.querystring.fileName',
            },
            integrationResponses: [{ statusCode: '200' }],
          },
        }),
        options: {
          requestParameters: {
            'method.request.querystring.fileName': true,
          },
          methodResponses: [{
            statusCode: '200',
          }],
        }
      },
    })
    .build(),
});

// Later, perhaps in another file, you can access the bucket property we defined
// in a type-safe manner
api.integrations.getFile.bucket.grantRead(...);

Terraform

Note

Overriding specific integrations is not supported with Terraform modules since they use the router pattern. All operations are handled by the single Lambda function.

For different integration types per operation, you would need to implement explicit integrations manually (see the Explicit Integrations section below).

Overriding Authorizers

CDK

You can also supply options in your integration to override particular method options such as authorizers, for example if you wished to use Cognito authentication for your getDocumentation operation:

new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOverrides({
      getDocumentation: {
        integration: new HttpIntegration('https://example.com/documentation'),
        options: {
          authorizer: new CognitoUserPoolsAuthorizer(...) // for REST, or HttpUserPoolAuthorizer for an HTTP API
        }
      },
    })
    .build(),
});

Terraform

Note

Per-operation authorizer overrides are not supported with Terraform modules. The entire API uses the authentication method specified when generating the API (IAM, Cognito, or None).

For per-operation authorization, you would need to implement explicit integrations manually as below.

Explicit Integrations

CDK

If you prefer, you can choose not to use the default integrations and instead directly supply one for each operation. This is useful if, for example, each operation needs to use a different type of integration or you would like to receive a type error when adding new operations:

new MyApi(this, 'MyApi', {
  integrations: {
    sayHello: {
      integration: new LambdaIntegration(...),
    },
    getDocumentation: {
      integration: new HttpIntegration(...),
    },
  },
});

Terraform

For explicit per-operation integrations with Terraform, you should modify the generated app-specific module to replace the default proxy integration with specific integrations for each operation.

Edit packages/common/terraform/src/app/apis/my-api/my-api.tf:

1. Remove the default proxy routes (e.g., resource "aws_apigatewayv2_route" "proxy_routes")
2. Replace the single Lambda function with individual functions for each operation
3. Create specific integrations and routes for each operation, reusing the same ZIP bundle:

HTTP API

packages/common/terraform/src/app/apis/my-api/my-api.tf

# Remove the default single Lambda function
 resource "aws_lambda_function" "api_lambda" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApiHandler"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "index.handler"
   runtime         = "nodejs22.x"
   timeout         = 30
   # ... rest of configuration
 }

# Remove the default proxy integration
 resource "aws_apigatewayv2_integration" "lambda_integration" {
   api_id           = module.http_api.api_id
   integration_type = "AWS_PROXY"
   integration_uri  = aws_lambda_function.api_lambda.invoke_arn
   # ... rest of configuration
 }

# Remove the default proxy routes
 resource "aws_apigatewayv2_route" "proxy_routes" {
   for_each = toset(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"])
   api_id    = module.http_api.api_id
   route_key = "${each.key} /{proxy+}"
   target    = "integrations/${aws_apigatewayv2_integration.lambda_integration.id}"
   # ... rest of configuration
 }

# Add individual Lambda functions for each operation using the same bundle
 resource "aws_lambda_function" "say_hello_handler" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-SayHello"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "sayHello.handler"  # Specific handler for this operation
   runtime         = "nodejs22.x"
   timeout         = 30
   source_code_hash = data.archive_file.lambda_zip.output_base64sha256

   tracing_config {
     mode = "Active"
   }

   environment {
     variables = merge({
       AWS_CONNECTION_REUSE_ENABLED = "1"
     }, var.env)
   }

   tags = var.tags
 }

 resource "aws_lambda_function" "get_documentation_handler" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-GetDocumentation"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "getDocumentation.handler"  # Specific handler for this operation
   runtime         = "nodejs22.x"
   timeout         = 30
   source_code_hash = data.archive_file.lambda_zip.output_base64sha256

   tracing_config {
     mode = "Active"
   }

   environment {
     variables = merge({
       AWS_CONNECTION_REUSE_ENABLED = "1"
     }, var.env)
   }

   tags = var.tags
 }

# Add specific integrations for each operation
 resource "aws_apigatewayv2_integration" "say_hello_integration" {
   api_id           = module.http_api.api_id
   integration_type = "AWS_PROXY"
   integration_uri  = aws_lambda_function.say_hello_handler.invoke_arn
   payload_format_version = "2.0"
   timeout_milliseconds   = 30000
 }

 resource "aws_apigatewayv2_integration" "get_documentation_integration" {
   api_id           = module.http_api.api_id
   integration_type = "HTTP_PROXY"
   integration_uri  = "https://example.com/documentation"
   integration_method = "GET"
 }

# Add specific routes for each operation
 resource "aws_apigatewayv2_route" "say_hello_route" {
   api_id    = module.http_api.api_id
   route_key = "POST /sayHello"
   target    = "integrations/${aws_apigatewayv2_integration.say_hello_integration.id}"
   authorization_type = "AWS_IAM"
 }

 resource "aws_apigatewayv2_route" "get_documentation_route" {
   api_id    = module.http_api.api_id
   route_key = "GET /documentation"
   target    = "integrations/${aws_apigatewayv2_integration.get_documentation_integration.id}"
   authorization_type = "NONE"
 }

# Add Lambda permissions for each function
 resource "aws_lambda_permission" "say_hello_permission" {
   statement_id  = "AllowExecutionFromAPIGateway-SayHello"
   action        = "lambda:InvokeFunction"
   function_name = aws_lambda_function.say_hello_handler.function_name
   principal     = "apigateway.amazonaws.com"
   source_arn    = "${module.http_api.api_execution_arn}/*/*"
 }

 resource "aws_lambda_permission" "get_documentation_permission" {
   statement_id  = "AllowExecutionFromAPIGateway-GetDocumentation"
   action        = "lambda:InvokeFunction"
   function_name = aws_lambda_function.get_documentation_handler.function_name
   principal     = "apigateway.amazonaws.com"
   source_arn    = "${module.http_api.api_execution_arn}/*/*"
 }

REST API

packages/common/terraform/src/app/apis/my-api/my-api.tf

# Remove the default single Lambda function
 resource "aws_lambda_function" "api_lambda" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApiHandler"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "index.handler"
   runtime         = "nodejs22.x"
   timeout         = 30
   # ... rest of configuration
 }

# Remove the default proxy integration
 resource "aws_apigatewayv2_integration" "lambda_integration" {
   api_id           = module.http_api.api_id
   integration_type = "AWS_PROXY"
   integration_uri  = aws_lambda_function.api_lambda.invoke_arn
   # ... rest of configuration
 }

# Remove the default proxy routes
 resource "aws_apigatewayv2_route" "proxy_routes" {
   for_each = toset(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"])
   api_id    = module.http_api.api_id
   route_key = "${each.key} /{proxy+}"
   target    = "integrations/${aws_apigatewayv2_integration.lambda_integration.id}"
   # ... rest of configuration
 }

# Add individual Lambda functions for each operation using the same bundle
 resource "aws_lambda_function" "say_hello_handler" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-SayHello"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "sayHello.handler"  # Specific handler for this operation
   runtime         = "nodejs22.x"
   timeout         = 30
   source_code_hash = data.archive_file.lambda_zip.output_base64sha256

   tracing_config {
     mode = "Active"
   }

   environment {
     variables = merge({
       AWS_CONNECTION_REUSE_ENABLED = "1"
     }, var.env)
   }

   tags = var.tags
 }

 resource "aws_lambda_function" "get_documentation_handler" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-GetDocumentation"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "getDocumentation.handler"  # Specific handler for this operation
   runtime         = "nodejs22.x"
   timeout         = 30
   source_code_hash = data.archive_file.lambda_zip.output_base64sha256

   tracing_config {
     mode = "Active"
   }

   environment {
     variables = merge({
       AWS_CONNECTION_REUSE_ENABLED = "1"
     }, var.env)
   }

   tags = var.tags
 }

# Add specific resources and methods for each operation
 resource "aws_api_gateway_resource" "say_hello_resource" {
   rest_api_id = module.rest_api.api_id
   parent_id   = module.rest_api.api_root_resource_id
   path_part   = "sayHello"
 }

 resource "aws_api_gateway_method" "say_hello_method" {
   rest_api_id   = module.rest_api.api_id
   resource_id   = aws_api_gateway_resource.say_hello_resource.id
   http_method   = "POST"
   authorization = "AWS_IAM"
 }

 resource "aws_api_gateway_integration" "say_hello_integration" {
   rest_api_id = module.rest_api.api_id
   resource_id = aws_api_gateway_resource.say_hello_resource.id
   http_method = aws_api_gateway_method.say_hello_method.http_method

   integration_http_method = "POST"
   type                   = "AWS_PROXY"
   uri                    = aws_lambda_function.say_hello_handler.invoke_arn
 }

 resource "aws_api_gateway_resource" "get_documentation_resource" {
   rest_api_id = module.rest_api.api_id
   parent_id   = module.rest_api.api_root_resource_id
   path_part   = "documentation"
 }

 resource "aws_api_gateway_method" "get_documentation_method" {
   rest_api_id   = module.rest_api.api_id
   resource_id   = aws_api_gateway_resource.get_documentation_resource.id
   http_method   = "GET"
   authorization = "NONE"
 }

 resource "aws_api_gateway_integration" "get_documentation_integration" {
   rest_api_id = module.rest_api.api_id
   resource_id = aws_api_gateway_resource.get_documentation_resource.id
   http_method = aws_api_gateway_method.get_documentation_method.http_method

   integration_http_method = "GET"
   type                   = "HTTP"
   uri                    = "https://example.com/documentation"
 }

# Update deployment to depend on new integrations
~ resource "aws_api_gateway_deployment" "api_deployment" {
    rest_api_id = module.rest_api.api_id

    depends_on = [
     aws_api_gateway_integration.lambda_integration,
     aws_api_gateway_integration.say_hello_integration,
     aws_api_gateway_integration.get_documentation_integration,
    ]

    lifecycle {
      create_before_destroy = true
    }

   triggers = {
     redeployment = sha1(jsonencode([
       aws_api_gateway_integration.say_hello_integration,
       aws_api_gateway_integration.get_documentation_integration,
     ]))
   }
  }

# Add Lambda permissions for each function
 resource "aws_lambda_permission" "say_hello_permission" {
   statement_id  = "AllowExecutionFromAPIGateway-SayHello"
   action        = "lambda:InvokeFunction"
   function_name = aws_lambda_function.say_hello_handler.function_name
   principal     = "apigateway.amazonaws.com"
   source_arn    = "${module.rest_api.api_execution_arn}/*/*"
 }

 resource "aws_lambda_permission" "get_documentation_permission" {
   statement_id  = "AllowExecutionFromAPIGateway-GetDocumentation"
   action        = "lambda:InvokeFunction"
   function_name = aws_lambda_function.get_documentation_handler.function_name
   principal     = "apigateway.amazonaws.com"
   source_arn    = "${module.rest_api.api_execution_arn}/*/*"
 }

Router Pattern

CDK

If you prefer to deploy a single Lambda function to service all API requests, you can freely edit the defaultIntegrations method for your API to create a single function instead of one per integration:

packages/common/constructs/src/app/apis/my-api.ts

export class MyApi<...> extends ... {

  public static defaultIntegrations = (scope: Construct) => {
    const router = new Function(scope, 'RouterHandler', { ... });
    return IntegrationBuilder.rest({
      ...
      defaultIntegrationOptions: {},
      buildDefaultIntegration: (op) => {
        return {
          // Reference the same router lambda handler in every integration
          integration: new LambdaIntegration(router),
        };
      },
    });
  };
}

You can modify the code in other ways if you prefer, for example you may prefer to define the router function as a parameter to defaultIntegrations instead of constructing it within the method.

Terraform

Terraform modules automatically use the router pattern - this is the default and only supported approach. The generated module creates a single Lambda function that handles all API operations.

You can simply instantiate the default module to get the router pattern:

# Default router pattern - single Lambda function for all operations
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  # Single Lambda function handles all operations automatically
  tags = local.common_tags
}

Code Generation

CDK

Since operations in FastAPI are defined in Python and CDK infrastructure in TypeScript, we instrument code-generation to supply metadata to the CDK construct to provide a type-safe interface for integrations.

A generate:<ApiName>-metadata target is added to the common constructs project.json to facilitate this code generation, which emits a file such as packages/common/constructs/src/generated/my-api/metadata.gen.ts. Since this is generated at build time, it is ignored in version control.

Note

You will need to run a build whenever you change your API to ensure the types consumed by the CDK construct are up to date.

pnpm

pnpm nx run-many --target build --all

yarn

yarn nx run-many --target build --all

npm

npx nx run-many --target build --all

bun

bunx nx run-many --target build --all

Tip

If you are actively working on both your CDK infrastructure and FastAPI together, you can use nx watch to regenerate these types every time you make API changes:

pnpm

pnpm nx watch --projects=<FastAPIProject> -- \
pnpm nx run <InfraProject>:"generate:<ApiName>-metadata"

yarn

yarn nx watch --projects=<FastAPIProject> -- \
yarn nx run <InfraProject>:"generate:<ApiName>-metadata"

npm

npx nx watch --projects=<FastAPIProject> -- \
npx nx run <InfraProject>:"generate:<ApiName>-metadata"

bun

bunx nx watch --projects=<FastAPIProject> -- \
bunx nx run <InfraProject>:"generate:<ApiName>-metadata"

Terraform

Note

We do not support type-safe integrations for Terraform, and therefore no code generation targets are configured if you selected Terraform for your iacProvider.

Granting Access (IAM Only)

If you selected to use IAM authentication, you can use the grantInvokeAccess method to grant access to your API:

CDK

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

Terraform

# Create an IAM policy to allow invoking the API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "MyApiInvokePolicy"
  description = "Policy to allow invoking the FastAPI"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = "execute-api:Invoke"
        Resource = "${module.my_api.api_execution_arn}/*/*"
      }
    ]
  })
}

# Attach the policy to an IAM role (e.g., for authenticated users)
resource "aws_iam_role_policy_attachment" "api_invoke_access" {
  role       = aws_iam_role.authenticated_user_role.name
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

# Or attach to an existing role by name
resource "aws_iam_role_policy_attachment" "api_invoke_access_existing" {
  role       = "MyExistingRole"
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

The key outputs from the API module that you can use for IAM policies are:

• module.my_api.api_execution_arn - For granting execute-api:Invoke permissions
• module.my_api.api_arn - The API Gateway ARN
• module.my_api.lambda_function_arn - The Lambda function ARN

Local Development

The generator configures a local development server that you can run with:

pnpm

pnpm nx run my-api:serve

yarn

yarn nx run my-api:serve

npm

npx nx run my-api:serve

bun

bunx nx run my-api:serve

This starts a local FastAPI development server with:

• Auto-reload on code changes
• Interactive API documentation at /docs or /redoc
• OpenAPI schema at /openapi.json

Invoking your FastAPI

To invoke your API from a React website, you can use the api-connection generator.