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:

Run this generator@aws/nx-plugin:py#api

CLI
VSCode

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

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

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

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

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

Build your command10

nameRequired

framework

integrationPattern

auth

Options

Generator Options10 options

nameRequiredstring: Name of the API project to generate
frameworkenumDefault: fastapi: The API framework to use.
fastapi
integrationPatternenumDefault: isolated: How API Gateway integrations are generated for the API. Choose between isolated (default) and shared.
isolatedshared
authenumDefault: iam: The method used to authenticate with your API. Choose between iam (default), cognito or custom.
iamcognitocustom
directorystringDefault: packages: The directory to store the application in.
iacenumDefault: inherit: The preferred IaC provider. By default this is inherited from your initial selection.
inheritcdkterraform
infraenumDefault: rest-lambda: The type of infrastructure to use to deploy this API.
rest-lambdahttp-lambdanone
subDirectorystring: The sub directory the project is placed in. By default this is the project name.
moduleNamestring: Python module name
preferInstallDependenciesbooleanDefault: true: Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

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
run.sh Lambda Web Adapter bootstrap script to start the FastAPI app via uvicorn
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 iac, 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
Terraform

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

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

For deploying your API, the following files are generated:

CDK
Terraform

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

Architecture

The deployed application has the following architecture: an API Gateway API in front of a Lambda function running your handler.

REST API
HTTP API

Loading the diagram…

REST APIs include an AWS WAFv2 Web ACL in front of the API Gateway stage with the AWS managed default ruleset enabled.

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 pydantic import BaseModel
from .init import app, tracer

class Item(BaseModel):
  name: str

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

@app.post("/items")
@tracer.capture_method
def create_item(item: Item) -> Item:
    return item

The generator sets up several features automatically:

AWS Lambda Powertools integration for observability
Error handling middleware
Request/response correlation
Metrics collection
AWS Lambda deployment via Lambda Web Adapter with uvicorn
Type-safe streaming (REST API only)

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, matched route and method

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
Per-route metrics (via a route dimension of <method> <path>)

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:

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

Accessing the Calling User

When your API is protected by authentication, your route handlers often need to know who is calling. The generated FastAPI runs inside AWS Lambda via the Lambda Web Adapter, which forwards the API Gateway request context as JSON on the x-amzn-request-context header. You can read it from the FastAPI Request to extract the caller’s identity.

As an example, let’s add a /me endpoint that returns details about the calling user. We’ll implement the extraction as a FastAPI dependency so it can be reused across routes. The shape of the request context — and therefore how you extract the identity — depends on both your selected auth method and whether you deployed a REST or HTTP API.

For IAM authentication, we look up the caller in Cognito using the sub extracted from the API Gateway request context, which requires boto3. Add it to your API project:

pnpm nx run my-api:add boto3==1.43.89

yarn nx run my-api:add boto3==1.43.89

npx nx run my-api:add boto3==1.43.89

bunx nx run my-api:add boto3==1.43.89

Create identity.py alongside main.py:

REST API
HTTP API

import json
import os
from typing import Annotated

from boto3 import client
from fastapi import Depends, HTTPException, Request
from pydantic import BaseModel

cognito = client("cognito-idp")


class Identity(BaseModel):
    sub: str
    username: str


def get_identity(request: Request) -> Identity:
    # The Lambda Web Adapter forwards the API Gateway request context as JSON
    request_context_header = request.headers.get("x-amzn-request-context")
    if not request_context_header:
        raise HTTPException(status_code=403, detail="Unable to determine calling user")

    request_context = json.loads(request_context_header)
    provider = request_context.get("identity", {}).get("cognitoAuthenticationProvider")

    sub = provider.split(":")[-1] if provider else None
    if not sub:
        raise HTTPException(status_code=403, detail="Unable to determine calling user")

    users = cognito.list_users(
        # Assumes user pool id is configured in lambda environment
        UserPoolId=os.environ["USER_POOL_ID"],
        Limit=1,
        Filter=f'sub="{sub}"',
    ).get("Users", [])

    if len(users) != 1:
        raise HTTPException(status_code=403, detail=f"No user found with subjectId {sub}")

    return Identity(sub=sub, username=users[0]["Username"])


CurrentUser = Annotated[Identity, Depends(get_identity)]

import json
import os
from typing import Annotated

from boto3 import client
from fastapi import Depends, HTTPException, Request
from pydantic import BaseModel

cognito = client("cognito-idp")


class Identity(BaseModel):
    sub: str
    username: str


def get_identity(request: Request) -> Identity:
    # The Lambda Web Adapter forwards the API Gateway request context as JSON
    request_context_header = request.headers.get("x-amzn-request-context")
    if not request_context_header:
        raise HTTPException(status_code=403, detail="Unable to determine calling user")

    request_context = json.loads(request_context_header)
    amr = (
        request_context.get("authorizer", {})
        .get("iam", {})
        .get("cognitoIdentity", {})
        .get("amr", [])
    )
    sign_in = next((s for s in amr if ":CognitoSignIn:" in s), None)
    sub = sign_in.split(":")[-1] if sign_in else None

    if not sub:
        raise HTTPException(status_code=403, detail="Unable to determine calling user")

    users = cognito.list_users(
        # Assumes user pool id is configured in lambda environment
        UserPoolId=os.environ["USER_POOL_ID"],
        Limit=1,
        Filter=f'sub="{sub}"',
    ).get("Users", [])

    if len(users) != 1:
        raise HTTPException(status_code=403, detail=f"No user found with subjectId {sub}")

    return Identity(sub=sub, username=users[0]["Username"])


CurrentUser = Annotated[Identity, Depends(get_identity)]

With auth: 'cognito', the API Gateway Cognito User Pools authorizer verifies the JWT that the caller supplies in the Authorization header and places the verified claims on the request context.

Create identity.py alongside main.py:

REST API
HTTP API

import json
from typing import Annotated

from fastapi import Depends, HTTPException, Request
from pydantic import BaseModel


class Identity(BaseModel):
    sub: str
    username: str


def get_identity(request: Request) -> Identity:
    # The Lambda Web Adapter forwards the API Gateway request context as JSON
    request_context_header = request.headers.get("x-amzn-request-context")
    if not request_context_header:
        raise HTTPException(status_code=403, detail="Unable to determine calling user")

    request_context = json.loads(request_context_header)
    claims = request_context.get("authorizer", {}).get("claims", {})

    sub = claims.get("sub")
    username = claims.get("username")

    if not sub or not username:
        raise HTTPException(status_code=403, detail="Unable to determine calling user")

    return Identity(sub=sub, username=username)


CurrentUser = Annotated[Identity, Depends(get_identity)]

HTTP APIs use a JWT authorizer which places the verified claims under authorizer.jwt.claims:

import json
from typing import Annotated

from fastapi import Depends, HTTPException, Request
from pydantic import BaseModel


class Identity(BaseModel):
    sub: str
    username: str


def get_identity(request: Request) -> Identity:
    # The Lambda Web Adapter forwards the API Gateway request context as JSON
    request_context_header = request.headers.get("x-amzn-request-context")
    if not request_context_header:
        raise HTTPException(status_code=403, detail="Unable to determine calling user")

    request_context = json.loads(request_context_header)
    claims = request_context.get("authorizer", {}).get("jwt", {}).get("claims", {})

    sub = claims.get("sub")
    username = claims.get("username")

    if not sub or not username:
        raise HTTPException(status_code=403, detail="Unable to determine calling user")

    return Identity(sub=sub, username=username)


CurrentUser = Annotated[Identity, Depends(get_identity)]

You can then inject the CurrentUser dependency into any route that needs the caller’s identity:

from .identity import CurrentUser, Identity
from .init import app, tracer

@app.get("/me")
@tracer.capture_method
def me(identity: CurrentUser) -> Identity:
    return identity

Streaming

The generated FastAPI supports streaming responses out of the box when using a REST API. The infrastructure is configured to use the AWS Lambda Web Adapter to run your FastAPI via uvicorn inside Lambda, with ResponseTransferMode.STREAM in API Gateway for all REST API operations, which enables streaming to work alongside non-streaming operations.

Using `JsonStreamingResponse`

The generated init.py exports a JsonStreamingResponse class that provides type-safe streaming with proper OpenAPI schema generation. This ensures that the connection generator can produce correctly typed streaming client methods.

from pydantic import BaseModel
from .init import app, JsonStreamingResponse

class Chunk(BaseModel):
    message: str

async def generate_chunks():
    for i in range(100):
        yield Chunk(message=f"This is chunk {i}")

@app.post(
    "/stream",
    response_class=JsonStreamingResponse,
    responses={200: JsonStreamingResponse.openapi_response(Chunk, "Stream of chunks")},
)
async def my_stream() -> JsonStreamingResponse:
    return JsonStreamingResponse(generate_chunks())

The JsonStreamingResponse class:

Serializes Pydantic models to JSON Lines format (application/jsonl)
Provides an openapi_response helper that generates the correct OpenAPI schema with itemSchema, enabling the connection generator to produce type-safe streaming client methods

Consumption

To consume a stream of responses, you can make use of the 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 iac. You can use this to deploy your FastAPI.

CDK
Terraform

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:

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

If your solution includes a website you can configure its CloudFront distribution as the only permitted CORS origin in the API gateway / API AWS Lambda integrations for HTTP / REST APIs. You can call the API restrictCorsTo method with website constructs, CloudFront distributions, origin strings, or a mix of them.

import { MyApi, MyWebsite } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
    const website = new MyWebsite(this, 'MyWebsite');
    api.restrictCorsTo(website, 'http://localhost:4200', 'http://localhost:4300');
  }
}

The MyWebsite construct can be generated using the ts#website generator. This example assumes the website’s local dev-server and preview ports are 4200/4300 - check its project.json (or vite.config.mts) for the ports actually assigned to it, since each website generated this way gets its own.

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#website#auth generator

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

The API module stages its Lambda deployment zip in a shared S3 asset bucket — see the Terraform infrastructure guide for details. Instantiate the core/asset-bucket module once per deployment and pass its bucket_name output into every API / Lambda module via the asset_bucket_name input:

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

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

  asset_bucket_name = module.asset_bucket.bucket_name

  # 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:

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

If your solution includes a Terraform website module then you can use its CloudFront domain name to restrict CORS. Given a CloudFront domain name <domain_name>, within the Terraform module for deploying your API add

a cors_allow_origins property, set to ["http://localhost:4200", "http://localhost:4300", "https://<domain name>"], for HTTP APIs. This restricts the API gateway CORS to this distribution and local host.
an ALLOWED_ORIGINS environment variable, set to "https://<domain_name>", for REST APIs. This sets the CloudFront distribution as the only permitted CORS origin (other than local host) in AWS Lambda integrations. Note that this restriction is not applied to preflight OPTIONS - please +1 this GitHub issue to help prioritise addressing this.

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

  asset_bucket_name = module.asset_bucket.bucket_name

  cors_allow_origins = ["http://localhost:4200", "http://localhost:4300", "https://<domain name>"] // Only required for HTTP API

  env = {
    ALLOWED_ORIGINS = "https://<domain name>" // Only required for REST API
    ENVIRONMENT = var.environment
    LOG_LEVEL   = "INFO"
  }
}

The MyWebsite construct can be generated using the ts#website generator. This example assumes the website’s local ports are 4200/4300 - check its project.json (or vite.config.mts) for the ports actually assigned to it, since each website generated this way gets its own.

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"

  asset_bucket_name    = module.asset_bucket.bucket_name

  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"

  asset_bucket_name = module.asset_bucket.bucket_name

  # 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
}

WAF

For REST APIs, the generated construct associates an AWS WAFv2 Web ACL with the API Gateway stage by default. The Web ACL uses the AWS managed default ruleset (AWSManagedRulesCommonRuleSet and AWSManagedRulesKnownBadInputsRuleSet), providing protection against common web exploits including the OWASP Top 10. WAF request logs are written to a CloudWatch Logs group.

You can edit the generated rest-api construct to add, remove, or adjust rules (for example, to add rate-based rules or additional managed rule groups).

CDK
Terraform

To opt out (for example, to attach your own Web ACL), set enableWaf to false:

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

To opt out (for example, to attach your own Web ACL), set enable_waf to false:

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

  asset_bucket_name = module.asset_bucket.bucket_name
  enable_waf        = false
}

Access logging

For REST APIs, the generated infrastructure enables access logging by default, writing one structured JSON line per request to a dedicated CloudWatch Logs group. The log group is encrypted with a customer-managed KMS key and retained for one year.

API Gateway writes access logs using an account-level CloudWatch Logs role. This role is configured on the AWS::ApiGateway::Account setting, which is a singleton per region per account — there is only one role for every REST API in the region. To manage this safely across multiple independently-deployed stacks, the generated infrastructure:

Creates a shared CloudWatch Logs role and configures it on the account only when no working role is already set, so deployments never overwrite a role another stack owns.
Leaves the account setting untouched on teardown, so destroying one stack never disables logging for other REST APIs in the region.

CDK
Terraform

The account role is managed by the ApiGatewayAccount construct, a stack-scoped singleton resolved via ApiGatewayAccount.ensure(scope). Each REST API’s stage depends on it, and the role is configured by a Lambda-backed custom resource.

The access log format is set by the RestApi construct your API extends. To customise it, pass deployOptions through to super in the generated packages/common/constructs/src/app/apis/my-api.ts, keeping the tracingEnabled the construct already sets:

super(scope, id, {
  apiName: 'MyApi',
  // ...
  deployOptions: {
    tracingEnabled: true,
    accessLogFormat: AccessLogFormat.clf(),
  },
  ...props,
});

AccessLogFormat is imported from aws-cdk-lib/aws-apigateway. Anything you leave unset keeps the construct’s default — a JSON format with the standard fields.

The account role is managed by the core/api/api-gateway-account module, which is instantiated by the generated API module. It configures the account idempotently and is never reset on terraform destroy.

You can customise the access log format by editing the access_log_settings block on the aws_api_gateway_stage resource in the generated API module.

Integrations

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

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

The generated module already defines the default integrations for the pattern the API was generated with, so no additional configuration is needed:

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

  asset_bucket_name = module.asset_bucket.bucket_name

  tags = local.common_tags
}

With the default isolated pattern, this creates one Lambda function per operation.

Accessing Integrations

CDK
Terraform

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: [...],
}));

If your API uses the shared pattern, the shared router Lambda is exposed as api.integrations.$router:

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

api.integrations.$router.handler.addEnvironment('LOG_LEVEL', 'DEBUG');

Note that $router is no longer available if you override every operation via withOverrides, since no operation is left using the default router integration.

With the isolated pattern, the module’s outputs are maps keyed by operation name, so you can reach a single operation’s resources. For example, to grant one operation’s Lambda function extra permissions:

# Grant additional permissions to just the sayHello operation's function
resource "aws_iam_role_policy" "say_hello_permissions" {
  name = "say-hello-additional-permissions"
  role = module.my_api.lambda_execution_role_names["sayHello"]

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

To grant the same permissions to every operation, iterate the operations output:

resource "aws_iam_role_policy" "additional_permissions" {
  for_each = toset(module.my_api.operations)

  name = "additional-api-permissions"
  role = module.my_api.lambda_execution_role_names[each.key]

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

The module also exposes lambda_function_names, lambda_function_arns, lambda_invoke_arns, integration_ids and lambda_log_group_names as maps keyed by operation name. With the shared pattern the equivalent singular outputs (lambda_execution_role_name, lambda_function_name, …) are exposed instead, since there is only one function.

Permissions every operation needs are better passed to the module, which applies them to each function’s role:

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

  asset_bucket_name = module.asset_bucket.bucket_name

  additional_iam_policy_statements = [
    {
      Effect   = "Allow"
      Action   = ["s3:GetObject"]
      Resource = ["arn:aws:s3:::my-bucket/*"]
    }
  ]
}

Customising Default Options

CDK
Terraform

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

VPC configuration is already supported by the generated module — set enable_vpc along with vpc_id and subnet_ids, and the module deploys every Lambda function into your VPC behind a shared security group it creates for you:

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

  asset_bucket_name = module.asset_bucket.bucket_name

  # VPC configuration
  enable_vpc = true
  vpc_id     = aws_vpc.main.id
  subnet_ids = [aws_subnet.private_a.id, aws_subnet.private_b.id]

  tags = local.common_tags
}

For options the module does not expose, edit the aws_lambda_function resource in the generated Terraform module directly. With the isolated pattern that single resource is declared for_each = local.operations, so an edit there applies to every operation.

Customising Options Per-Operation

CDK
Terraform

To customise the options used to create the default integration for specific operations (without affecting the others), you can use the withOperationOptions method. For example, if you would like to increase the Lambda function timeout for just one operation:

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOperationOptions({
      sayHello: {
        timeout: Duration.seconds(60),
      },
    })
    .build(),
});

// The selected operations remain default integrations, so they're still typed accordingly:
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({ ... }));

The options you specify are merged with the default integration options (and any options set via withDefaultOptions). Note that you cannot specify options for operations which you have replaced via withOverrides, since these no longer use the default integration.

You will encounter a type error if the same operation is targeted by both withOperationOptions and withOverrides, regardless of the order in which you call them.

With the isolated pattern the Lambda function resource is already per-operation, so options can be varied by operation name. For example, to give one operation a longer timeout, edit the aws_lambda_function resource in the generated module:

resource "aws_lambda_function" "api_lambda" {
  for_each = local.operations

  # Default to 30 seconds, but allow longer for specific operations
  timeout = lookup({
    sayHello = 60
  }, each.key, 30)

  # ... rest of configuration
}

Overriding Integrations

CDK
Terraform

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(...);

To point a specific operation at a different integration type, exclude it from the default for_each and declare its integration separately. For example, to serve getDocumentation from an external website:

# Exclude the overridden operation from the default per-operation resources
locals {
  overridden_operations = ["getDocumentation"]
  default_operations = {
    for op, details in local.operations : op => details
    if !contains(local.overridden_operations, op)
  }
}

# Then use local.default_operations in place of local.operations for the
# aws_lambda_function, aws_iam_role, aws_apigatewayv2_integration and
# aws_lambda_permission resources, and add the override:
resource "aws_apigatewayv2_integration" "get_documentation" {
  api_id             = module.http_api.api_id
  integration_type   = "HTTP_PROXY"
  integration_uri    = "https://example.com/documentation"
  integration_method = "GET"
}

resource "aws_apigatewayv2_route" "get_documentation" {
  api_id    = module.http_api.api_id
  route_key = local.route_key["getDocumentation"]
  target    = "integrations/${aws_apigatewayv2_integration.get_documentation.id}"
}

Overriding Authorizers

CDK
Terraform

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

Authorization is set on the route (HTTP API) or method (REST API) for each operation, so it can be varied by operation name. For example, to leave one operation unauthenticated on an HTTP API:

resource "aws_apigatewayv2_route" "operation_routes" {
  for_each = local.operations

  # ... rest of configuration

  authorization_type = each.key == "getDocumentation" ? "NONE" : "AWS_IAM"
}

For an IAM-authenticated REST API, also add a resource policy statement allowing unauthenticated access to that operation’s path.

Explicit Integrations

CDK
Terraform

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

Replace the for_each used by the isolated pattern with explicit instantiations of the Lambda functions, integrations and permissions for each operation.

Integration Pattern

Generated APIs support two integration patterns:

isolated creates one Lambda function per operation. This is the default and recommended option for APIs.
shared creates a single default router Lambda and reuses it for every operation unless you override specific integrations.

isolated gives you finer-grained permissions and configuration per operation, as well as better separation for logs and traces. shared reduces the likelihood of encountering cold-starts for low-usage APIs.

CDK
Terraform

The integration pattern can be changed at any time in CDK by updating your API construct. For example, setting pattern to 'shared' creates a single function instead of one per integration:

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

  public static defaultIntegrations = (scope: Construct) => {
    ...
    return IntegrationBuilder.rest({
      pattern: 'shared',
      ...
    });
  };
}

Unlike CDK, the integration pattern is baked into the generated module. To change the integration pattern:

Delete the previously generated API module in packages/common/terraform/src/app/apis
Re-run the generator that created your API with the other integration pattern (eg --integrationPattern=shared)

With the isolated pattern, the module reads the operations from a generated file:

locals {
  operations_file = "${path.module}/../../../generated/my-api/operations.json"
  operations      = fileexists(local.operations_file) ? jsondecode(file(local.operations_file)) : {}
}

This file is generated from your API, so you do not need to edit this by hand. Adding an operation to your API application code adds the route and lambda function on the next deploy. It is .gitignored by default; remove the entry if you prefer to check it in.

Terraform REST API Path Depth Limit

Due to a limitation with Terraform where instances of resources can’t reference one another (see hashicorp/terraform#26697), the API Gateway resource tree is built one level at a time rather than recursively, supporting operation paths of up to 16 segments. If an operation’s path exceeds this, the plan fails with a message naming the paths that are too deep.

Click here for instructions to support deeper paths should your API require it

Code Generation

CDK
Terraform

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.

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 build

yarn build

npm run build

bun build

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 nx watch --projects=<FastAPIProject> -- \
pnpm nx run @<scope>/common-constructs:"generate:<ApiName>-metadata"

yarn nx watch --projects=<FastAPIProject> -- \
yarn nx run @<scope>/common-constructs:"generate:<ApiName>-metadata"

npx nx watch --projects=<FastAPIProject> -- \
npx nx run @<scope>/common-constructs:"generate:<ApiName>-metadata"

bunx nx watch --projects=<FastAPIProject> -- \
bunx nx run @<scope>/common-constructs:"generate:<ApiName>-metadata"

nx watch requires the Nx daemon, which is enabled by default but switched off inside CI, Docker containers and sandboxed environments. Where it is off, the command exits with Daemon is not running — set NX_DAEMON=true to enable it.

Granting Access (IAM Only)

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

CDK
Terraform

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

# 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 nx serve <project-name>

yarn nx serve <project-name>

npx nx serve <project-name>

bunx nx serve <project-name>

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 connection generator.

Connections

Use the connection generator to integrate this project with others in your workspace. The following connections involve this project:

React to FastAPICall a Python FastAPI from a React website

FastAPI to Python DynamoDBConnect a FastAPI to a DynamoDB table