FastAPI

FastAPI es un framework para construir APIs en Python.

El generador de FastAPI crea una nueva FastAPI con configuración de infraestructura usando AWS CDK o Terraform. El backend generado utiliza AWS Lambda para despliegue serverless, expuesto a través de una API de AWS API Gateway. Configura AWS Lambda Powertools para observabilidad, incluyendo registro, trazado con AWS X-Ray y métricas de CloudWatch.

Uso

Generar una API FastAPI

Puedes generar una nueva API FastAPI de dos maneras:

VSCode
CLI

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - py#fast-api
Complete los parámetros requeridos
Haga clic en Generate

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

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

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

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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

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

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

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	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.
integrationPattern	string	isolated	How API Gateway integrations are generated for the API. Choose between isolated (default) and shared.
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	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.
moduleName	string	-	Python module name

Salida del generador

El generador creará la siguiente estructura de proyecto en el directorio <directory>/<api-name>:

project.json Configuración del proyecto y objetivos de build
pyproject.toml Configuración del proyecto Python y dependencias
run.sh Script de arranque de Lambda Web Adapter para iniciar la app FastAPI mediante uvicorn
Directorio<module_name>
- __init__.py Inicialización del módulo
- init.py Configura la aplicación FastAPI y el middleware de powertools
- main.py Implementación de la API
Directorioscripts
- generate_open_api.py Script para generar un esquema OpenAPI desde la app FastAPI

Infraestructura

Dado que este generador proporciona infraestructura como código basada en tu proveedor de iacProvider seleccionado, creará un proyecto en packages/common que incluye los constructos CDK o módulos de Terraform correspondientes.

El proyecto común de infraestructura como código tiene la siguiente estructura:

CDK
Terraform

Directoriopackages/common/constructs
- Directoriosrc
  - Directorioapp/ Constructos para infraestructura específica de un proyecto/generador
    …
  - Directoriocore/ Constructos genéricos reutilizados por los constructos en app
    …
  - index.ts Punto de entrada que exporta los constructos de app
- project.json Objetivos de compilación y configuración del proyecto

Directoriopackages/common/terraform
- Directoriosrc
  - Directorioapp/ Módulos de Terraform para infraestructura específica de un proyecto/generador
    …
  - Directoriocore/ Módulos genéricos reutilizados por los módulos en app
    …
- project.json Objetivos de compilación y configuración del proyecto

Para implementar tu API, se generan los siguientes archivos:

CDK
Terraform

Directoriopackages/common/constructs/src
- Directorioapp
  - Directorioapis
    <project-name>.ts Constructo de CDK para implementar tu API
- Directoriocore
  - Directorioapi
    http-api.ts Constructo de CDK para implementar una API HTTP (si seleccionaste implementar una API HTTP)
    rest-api.ts Constructo de CDK para implementar una API REST (si seleccionaste implementar una API REST)
    utils.ts Utilidades para los constructos de API

Implementando tu API FastAPI

La implementación principal de la API está en main.py. Aquí es donde defines las rutas de tu API y sus implementaciones. Aquí un ejemplo:

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=...)

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

El generador configura automáticamente varias características:

Integración de AWS Lambda Powertools para observabilidad
Middleware de manejo de errores
Correlación de solicitudes/respuestas
Recolección de métricas
Despliegue en AWS Lambda mediante Lambda Web Adapter con uvicorn
Streaming con tipos seguros (solo REST API)

Observabilidad con AWS Lambda Powertools

Registro

El generador configura registro estructurado usando AWS Lambda Powertools. Puedes acceder al logger en tus manejadores de rutas:

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}

El logger incluye automáticamente:

IDs de correlación para trazado de solicitudes
Ruta y método de la solicitud
Información del contexto de Lambda
Indicadores de inicio en frío

Seguimiento

El trazado con AWS X-Ray se configura automáticamente. Puedes añadir subsegmentos personalizados a tus trazas:

from .init import app, tracer

@app.get("/items/{item_id}")
@tracer.capture_method
def read_item(item_id: int):
    # Crea un nuevo subsegmento
    with tracer.provider.in_subsegment("fetch-item-details"):
        # Tu lógica aquí
        return {"item_id": item_id}

Métricas

Las métricas de CloudWatch se recopilan automáticamente para cada solicitud. Puedes añadir métricas personalizadas:

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}

Las métricas por defecto incluyen:

Conteo de solicitudes
Conteos de éxito/fallo
Métricas de inicio en frío
Métricas por ruta

Manejo de errores

El generador incluye manejo de errores completo:

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}

Las excepciones no manejadas son capturadas por el middleware y:

Registran la excepción completa con stack trace
Registran una métrica de fallo
Devuelven una respuesta segura 500 al cliente
Preservan el ID de correlación

Streaming

La FastAPI generada soporta respuestas en streaming de forma predeterminada cuando se usa una REST API. La infraestructura está configurada para usar el AWS Lambda Web Adapter para ejecutar tu FastAPI mediante uvicorn dentro de Lambda, con ResponseTransferMode.STREAM en API Gateway para todas las operaciones de REST API, lo que permite que el streaming funcione junto con operaciones que no son de streaming.

Usando `JsonStreamingResponse`

El init.py generado exporta una clase JsonStreamingResponse que proporciona streaming con tipos seguros y generación adecuada del esquema OpenAPI. Esto asegura que el generador connection pueda producir métodos de cliente de streaming correctamente tipados.

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

La clase JsonStreamingResponse:

Serializa modelos Pydantic al formato JSON Lines (application/jsonl)
Proporciona un helper openapi_response que genera el esquema OpenAPI correcto con itemSchema, permitiendo que el generador connection produzca métodos de cliente de streaming con tipos seguros

Consumo

Para consumir un stream de respuestas, puedes usar el generador connection que provee un método tipado para iterar sobre los fragmentos transmitidos.

Desplegando tu API FastAPI

El generador de FastAPI crea código de infraestructura CDK o Terraform según tu iacProvider seleccionado. Puedes usarlo para desplegar tu API FastAPI.

CDK
Terraform

El constructo CDK para desplegar tu API está en la carpeta common/constructs. Puedes usarlo en una aplicación CDK:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Añadir la API al stack
    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Esto configura:

Una función AWS Lambda por cada operación en la aplicación FastAPI
API Gateway HTTP/REST API como trigger de la función
Roles y permisos IAM
Grupo de logs de CloudWatch
Configuración de trazado X-Ray
Namespace de métricas CloudWatch

Si tu solución incluye un sitio web, puedes configurar su distribución de CloudFront como el único origen CORS permitido en el API gateway / integraciones de API AWS Lambda para APIs HTTP / REST. Puedes llamar al método restrictCorsTo de la API con constructos de sitios web, distribuciones de CloudFront, cadenas de origen, o una combinación de ellos.

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

El constructo MyWebsite puede ser generado usando el generador ts#react-website

Si seleccionaste autenticación Cognito, debes proveer la propiedad identity al constructo de la API:

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

El constructo UserIdentity puede generarse con el generador ts#react-website-auth

Los módulos Terraform para desplegar tu API están en la carpeta common/terraform. Puedes usarlos en una configuración Terraform:

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

  # Variables de entorno para la función Lambda
  env = {
    ENVIRONMENT = var.environment
    LOG_LEVEL   = "INFO"
  }

  # Políticas IAM adicionales si es necesario
  additional_iam_policy_statements = [
    # Añade los permisos adicionales que tu API necesite
  ]

  tags = local.common_tags
}

Esto configura:

Una función Lambda que sirve todas las rutas de FastAPI
API Gateway HTTP/REST API como trigger de la función
Roles y permisos IAM
Grupo de logs CloudWatch
Configuración de trazado X-Ray
Configuración CORS

Si su solución incluye un módulo de sitio web de Terraform, entonces puede usar su nombre de dominio de CloudFront para restringir CORS. Dado un nombre de dominio de CloudFront <domain_name>, dentro del módulo de Terraform para implementar su API agregue

una propiedad cors_allow_origins, establecida en ["http://localhost:4200", "http://localhost:4300", "https://<domain name>"], para APIs HTTP. Esto restringe el CORS del gateway de API a esta distribución y host local.
una variable de entorno ALLOWED_ORIGINS, establecida en "https://<domain_name>", para APIs REST. Esto establece la distribución de CloudFront como el único origen CORS permitido (aparte de host local) en las integraciones de AWS Lambda. Tenga en cuenta que esta restricción no se aplica a las solicitudes preflight OPTIONS - por favor +1 este issue de GitHub para ayudar a priorizar la resolución de esto.

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

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

El constructo MyWebsite puede ser generado usando el generador ts#react-website

Si seleccionaste autenticación Cognito, debes proveer su configuración:

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
}

Puedes configurar Cognito User Pool y Client usando los recursos o módulos Terraform apropiados.

El módulo Terraform provee varios outputs que puedes usar:

# Acceder al endpoint de la API
output "api_url" {
  value = module.my_api.stage_invoke_url
}

# Acceder a los detalles de la función Lambda
output "lambda_function_name" {
  value = module.my_api.lambda_function_name
}

# Acceder al rol IAM para conceder permisos adicionales
output "lambda_execution_role_arn" {
  value = module.my_api.lambda_execution_role_arn
}

Puedes personalizar la configuración CORS pasando variables al módulo:

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

  # Configuración CORS personalizada
  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
}

Si seleccionaste None para auth al ejecutar el generador, puedes ver fallos en checks de Checkov como:

HTTP API
REST API

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

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

Puedes añadir un comentario de supresión si estás seguro de que deseas que tu API sea pública.

Integraciones

Los constructos CDK de la API REST/HTTP están configurados para proporcionar una interfaz type-safe que define integraciones para cada una de tus operaciones.

CDK
Terraform

Los constructos CDK proporcionan soporte completo de integración con seguridad de tipos como se describe a continuación.

Puedes usar el método estático defaultIntegrations para utilizar el patrón por defecto, que define una función AWS Lambda individual para cada operación:

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

Los módulos de Terraform usan automáticamente el patrón router con una única función Lambda. No se necesita configuración adicional:

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

  # El módulo crea automáticamente una única función Lambda
  # que maneja todas las operaciones de la API
  tags = local.common_tags
}

Accediendo a las integraciones

CDK
Terraform

Puedes acceder a las funciones AWS Lambda subyacentes a través de la propiedad integrations del constructo de la API, de manera type-safe. Por ejemplo, si tu API define una operación llamada sayHello y necesitas agregar permisos a esta función, puedes hacerlo así:

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

// sayHello está tipado según las operaciones definidas en tu API
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
  effect: Effect.ALLOW,
  actions: [...],
  resources: [...],
}));

Si tu API usa el patrón shared, el router Lambda compartido se expone como api.integrations.$router:

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

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

Con el patrón router de Terraform, solo hay una función Lambda. Puedes acceder a ella a través de los outputs del módulo:

# Otorgar permisos adicionales a la única función Lambda
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/*"
      }
    ]
  })
}

Personalizando opciones por defecto

CDK
Terraform

Si deseas personalizar las opciones usadas al crear la función Lambda para cada integración por defecto, puedes usar el método withDefaultOptions. Por ejemplo, si quieres que todas tus funciones Lambda residan en una VPC:

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

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

Si especificas environment en tus opciones por defecto, esto sobrescribirá cualquier variable de entorno que esté definida dentro de tu constructo de API generado. Generalmente es preferible usar el método addEnvironment para las funciones Lambda. Puedes lograr esto fácilmente iterando a través de tus integraciones:

Object.values(api.integrations).forEach(({ handler }) => {
  handler.addEnvironment('LOG_LEVEL', 'INFO');
});

Para personalizar opciones como configuración de VPC, necesitas editar el módulo de Terraform generado. Por ejemplo, para agregar soporte de VPC a todas las funciones Lambda:

# Agregar variables de VPC
variable "vpc_subnet_ids" {
  description = "Lista de IDs de subredes VPC para la función Lambda"
  type        = list(string)
  default     = []
}

variable "vpc_security_group_ids" {
  description = "Lista de IDs de grupos de seguridad VPC para la función Lambda"
  type        = list(string)
  default     = []
}

# Actualizar el recurso de función Lambda
resource "aws_lambda_function" "api_lambda" {
  # ... configuración existente ...

  # Agregar configuración VPC
  vpc_config {
    subnet_ids         = var.vpc_subnet_ids
    security_group_ids = var.vpc_security_group_ids
  }
}

Luego usar el módulo con configuración VPC:

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

  # Configuración VPC
  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
}

Sobrescribiendo integraciones

CDK
Terraform

También puedes sobrescribir integraciones para operaciones específicas usando el método withOverrides. Cada override debe especificar una propiedad integration que está tipada al constructo de integración CDK apropiado para la API HTTP o REST. El método withOverrides también es type-safe. Por ejemplo, si quieres sobrescribir una API getDocumentation para apuntar a documentación alojada en un sitio externo:

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

Notarás que la integración sobrescrita ya no tiene una propiedad handler cuando se accede a través de api.integrations.getDocumentation.

Puedes agregar propiedades adicionales a una integración que también estarán tipadas, permitiendo abstraer otros tipos de integración manteniendo el type-safe. Por ejemplo, si creaste una integración S3 para una API REST y luego quieres referenciar el bucket para una operación particular:

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

// Más tarde, quizás en otro archivo, puedes acceder a la propiedad bucket que definimos
// de manera type-safe
api.integrations.getFile.bucket.grantRead(...);

Sobrescribiendo autorizadores

CDK
Terraform

También puedes proveer options en tu integración para sobrescribir opciones de método específicas como autorizadores. Por ejemplo, si deseas usar autenticación con Cognito para tu operación getDocumentation:

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

Integraciones explícitas

CDK
Terraform

Si prefieres, puedes no usar las integraciones por defecto y proveer directamente una para cada operación. Esto es útil si, por ejemplo, cada operación necesita usar un tipo diferente de integración o quieres recibir un error de tipo al agregar nuevas operaciones:

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

Para integraciones explícitas por operación con Terraform, debes modificar el módulo específico de la aplicación generado para reemplazar la integración proxy por defecto con integraciones específicas para cada operación.

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

Eliminar las rutas proxy por defecto (ej. resource "aws_apigatewayv2_route" "proxy_routes")
Reemplazar la única función Lambda con funciones individuales para cada operación
Crear integraciones y rutas específicas para cada operación, reusando el mismo paquete ZIP:

HTTP API
REST API

# Eliminar la función Lambda única por defecto
 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
   # ... resto de la configuración
 }

# Eliminar la integración proxy por defecto
 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
   # ... resto de la configuración
 }

# Eliminar las rutas proxy por defecto
 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}"
   # ... resto de la configuración
 }

# Agregar funciones Lambda individuales para cada operación usando el mismo 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"  # Handler específico para esta operación
   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"  # Handler específico para esta operación
   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
 }

# Agregar integraciones específicas para cada operación
 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"
 }

# Agregar rutas específicas para cada operación
 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"
 }

# Agregar permisos Lambda para cada función
 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}/*/*"
 }

# Eliminar la función Lambda única por defecto
 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
   # ... resto de la configuración
 }

# Eliminar la integración proxy por defecto
 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
   # ... resto de la configuración
 }

# Eliminar las rutas proxy por defecto
 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}"
   # ... resto de la configuración
 }

# Agregar funciones Lambda individuales para cada operación usando el mismo 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"  # Handler específico para esta operación
   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"  # Handler específico para esta operación
   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
 }

# Agregar recursos y métodos específicos para cada operación
 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"
 }

# Actualizar deployment para depender de nuevas integraciones
~ 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,
     ]))
   }
  }

# Agregar permisos Lambda para cada función
 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}/*/*"
 }

Patrón de Integración

CDK
Terraform

Los constructos de API CDK generados admiten dos patrones de integración:

isolated crea una función Lambda por operación. Este es el valor por defecto para las APIs generadas.
shared crea un único router Lambda por defecto y lo reutiliza para cada operación a menos que sobrescribas integraciones específicas.

isolated te brinda permisos y configuración más granulares por operación. shared reduce la proliferación de funciones Lambda e integraciones de API Gateway mientras aún permite sobrescritas selectivas.

Por ejemplo, establecer pattern a 'shared' crea una única función en lugar de una por integración:

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

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

Los módulos de Terraform usan automáticamente el patrón router - este es el enfoque por defecto y único soportado. El módulo generado crea una única función Lambda que maneja todas las operaciones de la API.

Simplemente instancia el módulo por defecto para obtener el patrón router:

# Patrón router por defecto - única función Lambda para todas las operaciones
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  # Una única función Lambda maneja todas las operaciones automáticamente
  tags = local.common_tags
}

Generación de código

CDK
Terraform

Dado que las operaciones en FastAPI se definen en Python y la infraestructura CDK en TypeScript, instrumentamos generación de código para proveer metadatos al constructo CDK y proporcionar una interfaz tipada para las integraciones.

Se añade un target generate:<ApiName>-metadata al project.json de los constructos comunes para facilitar esta generación de código, que emite un archivo como packages/common/constructs/src/generated/my-api/metadata.gen.ts. Dado que esto se genera en tiempo de build, se ignora en control de versiones.

Debes ejecutar un build cada vez que cambies tu API para asegurar que los tipos consumidos por el constructo CDK estén actualizados.

pnpm build

yarn build

npm run build

bun build

Si trabajas activamente en tu infraestructura CDK y FastAPI simultáneamente, puedes usar nx watch para regenerar estos tipos cada vez que hagas cambios en la API:

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

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

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

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

Concediendo acceso (solo IAM)

Si seleccionaste autenticación IAM, puedes usar el método grantInvokeAccess para conceder acceso a tu API:

CDK
Terraform

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

# Crear una política IAM para permitir invocar la API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "MyApiInvokePolicy"
  description = "Política para permitir invocar la FastAPI"

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

# Adjuntar la política a un rol IAM (por ejemplo, para usuarios autenticados)
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
}

# O adjuntar a un rol existente por nombre
resource "aws_iam_role_policy_attachment" "api_invoke_access_existing" {
  role       = "MyExistingRole"
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

Los outputs clave del módulo API que puedes usar para políticas IAM son:

module.my_api.api_execution_arn - Para conceder permisos execute-api:Invoke
module.my_api.api_arn - El ARN de API Gateway
module.my_api.lambda_function_arn - El ARN de la función Lambda

Desarrollo local

El generador configura un servidor de desarrollo local que puedes ejecutar con:

pnpm nx run my-api:serve

yarn nx run my-api:serve

npx nx run my-api:serve

bunx nx run my-api:serve

Esto inicia un servidor de desarrollo FastAPI local con:

Recarga automática al cambiar el código
Documentación interactiva de la API en /docs o /redoc
Esquema OpenAPI en /openapi.json

Invocando tu API FastAPI

Para invocar tu API desde un sitio React, puedes usar el generador connection.