FastAPI

FastAPI es un framework para construir APIs en Python.

El generador de FastAPI crea una nueva FastAPI con configuración de infraestructura 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 logging, trazado de AWS X-Ray y métricas de Cloudwatch.

Uso

Generar una FastAPI

Puedes generar una nueva FastAPI de dos maneras:

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#api --framework=fastapi

yarn

yarn nx g @aws/nx-plugin:py#api --framework=fastapi

npm

npx nx g @aws/nx-plugin:py#api --framework=fastapi

bun

bunx nx g @aws/nx-plugin:py#api --framework=fastapi

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

pnpm

pnpm nx g @aws/nx-plugin:py#api --framework=fastapi --dry-run

yarn

yarn nx g @aws/nx-plugin:py#api --framework=fastapi --dry-run

npm

npx nx g @aws/nx-plugin:py#api --framework=fastapi --dry-run

bun

bunx nx g @aws/nx-plugin:py#api --framework=fastapi --dry-run

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - py#api
5. Complete los parámetros requeridos
   • framework: fastapi
6. Haga clic en Generate

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	string	-	Nombre del proyecto de API a generar
framework	fastapi	fastapi	El framework de API a utilizar.
integrationPattern	isolated | shared	isolated	Cómo se generan las integraciones de API Gateway para la API. Elija entre isolated (predeterminado) y shared.
auth	iam | cognito | custom	iam	El método utilizado para autenticar con tu API. Elige entre iam (predeterminado), cognito o custom.
directory	string	packages	El directorio donde almacenar la aplicación.
subDirectory	string	-	El subdirectorio en el que se coloca el proyecto. Por defecto, este es el nombre del proyecto.
iac	inherit | cdk | terraform	inherit	El proveedor de IaC preferido. Por defecto, se hereda de tu selección inicial.
moduleName	string	-	Nombre del módulo Python
infra	rest-lambda | http-lambda | none	rest-lambda	El tipo de infraestructura a utilizar para desplegar esta API.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al procesar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsecuentes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Elección del tipo de API

Puedes elegir entre una REST API o una HTTP API para desplegar tu API, consulta la API Gateway Developer Guide para ayudarte a decidir.

Tipo de API

Selecciona rest-lambda (predeterminado) como tu infra si tienes la intención de construir cualquier operación de streaming.

Patrón de Integración

La opción integrationPattern tiene como valor predeterminado isolated, que crea una Lambda por operación de FastAPI. Selecciona shared si prefieres un único manejador Lambda compartido para toda la API, con anulaciones opcionales por operación.

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 construcción
• pyproject.toml Configuración del proyecto Python y dependencias
• run.sh Script de arranque de Lambda Web Adapter para iniciar la aplicación FastAPI a través de uvicorn
• Directorio<module_name>

  • __init__.py Inicialización del módulo
  • init.py Configura la aplicación FastAPI y configura el middleware de powertools
  • main.py Implementación de la API
• Directorioscripts

  • generate_open_api.py Script para generar un esquema OpenAPI desde la aplicación FastAPI

Infraestructura

Dado que este generador proporciona infraestructura como código basada en tu iac elegido, creará un proyecto en packages/common que incluye las construcciones CDK o módulos Terraform relevantes.

El proyecto común de infraestructura como código está estructurado de la siguiente manera:

CDK

• Directoriopackages/common/constructs

  • Directoriosrc

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

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

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

Proyecto Generado

Este proyecto se genera utilizando el generador ts#project y por lo tanto configura los mismos objetivos de compilación.

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

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

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

      • …
  • project.json Project build targets and configuration

Proyecto Generado

Este proyecto se genera utilizando el generador terraform#project y por lo tanto configura los mismos objetivos de compilación.

Para desplegar tu API, se generan los siguientes archivos:

CDK

• Directoriopackages/common/constructs/src

  • Directorioapp

    • Directorioapis

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

    • Directorioapi

      • 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

• Directoriopackages/common/terraform/src

  • Directorioapp

    • Directorioapis

      • Directorio<project-name>

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

    • Directorioapi

      • Directoriohttp-api

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

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

Arquitectura

La aplicación desplegada tiene la siguiente arquitectura:

REST API

Las REST APIs incluyen una Web ACL de AWS WAFv2 frente a la etapa de API Gateway con el conjunto de reglas predeterminado administrado por AWS habilitado.

HTTP API

Las HTTP APIs no admiten WAF directamente — si necesitas protección WAF, elige REST API en su lugar o coloca la HTTP API detrás de una distribución de CloudFront.

Implementar tu FastAPI

La implementación principal de la API está en main.py. Aquí es donde defines tus rutas de API y sus implementaciones. Aquí hay 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 varias características automáticamente:

1. Integración de AWS Lambda Powertools para observabilidad
2. Middleware de manejo de errores
3. Correlación de solicitud/respuesta
4. Recopilación de métricas
5. Despliegue de AWS Lambda a través de Lambda Web Adapter con uvicorn
6. Streaming con seguridad de tipos (solo API REST)

Observabilidad con AWS Lambda Powertools

Logging

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

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 el rastreo de solicitudes
• Ruta de solicitud, ruta coincidente y método

Trazado

El trazado de AWS X-Ray se configura automáticamente. Puedes agregar subsegmentos personalizados a tus trazas:

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}

Métricas

Las métricas de CloudWatch se recopilan automáticamente para cada solicitud. Puedes agregar 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 predeterminadas incluyen:

• Conteos de solicitudes
• Conteos de éxito/fallo
• Métricas por ruta (a través de una dimensión route de <method> <path>)

Manejo de Errores

El generador incluye manejo de errores integral:

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:

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

Modelos de Respuesta

Se recomienda especificar modelos de respuesta para tus operaciones de API para una mejor generación de código si usas el generador connection. Consulta aquí para más detalles.

Acceder al Usuario que Llama

Cuando tu API está protegida por autenticación, tus manejadores de ruta a menudo necesitan saber quién está llamando. La FastAPI generada se ejecuta dentro de AWS Lambda a través del Lambda Web Adapter, que reenvía el contexto de solicitud de API Gateway como JSON en el encabezado x-amzn-request-context. Puedes leerlo desde el Request de FastAPI para extraer la identidad del llamador.

Como ejemplo, agreguemos un endpoint /me que devuelva detalles sobre el usuario que llama. Implementaremos la extracción como una dependencia de FastAPI para que pueda reutilizarse en todas las rutas. La forma del contexto de solicitud — y por lo tanto cómo extraes la identidad — depende tanto de tu método auth seleccionado como de si desplegaste una API REST o HTTP.

auth = iam

Para autenticación IAM, buscamos al llamador en Cognito usando el sub extraído del contexto de solicitud de API Gateway. Crea identity.py junto a main.py:

REST 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)]

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

auth = cognito

Con auth: 'cognito', el autorizador de Cognito User Pools de API Gateway verifica el JWT que el llamador proporciona en el encabezado Authorization y coloca las reclamaciones verificadas en el contexto de solicitud.

Crea identity.py junto a main.py:

REST 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 API

Las APIs HTTP usan un autorizador JWT que coloca las reclamaciones verificadas bajo 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)]

No se requiere verificación de token

No necesitas ninguna biblioteca de verificación JWT aquí — el autorizador de Cognito User Pools de API Gateway ya ha verificado la firma, el emisor, los alcances y la expiración para cuando se ejecuta tu Lambda. Si alguna de esas verificaciones falla, API Gateway devuelve 401 Unauthorized y tu manejador nunca se invoca.

Luego puedes inyectar la dependencia CurrentUser en cualquier ruta que necesite la identidad del llamador:

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

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

infra = rest-lambda

Streaming

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

Usar JsonStreamingResponse

El init.py generado exporta una clase JsonStreamingResponse que proporciona streaming con seguridad de tipos y generación adecuada de 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:

1. Serializa modelos Pydantic al formato JSON Lines (application/jsonl)
2. 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 seguridad de tipos

Consumo

Para consumir un flujo de respuestas, puedes hacer uso del generador connection que proporcionará un método con seguridad de tipos para iterar sobre tus fragmentos transmitidos.

Desplegar tu FastAPI

El generador de FastAPI crea infraestructura como código CDK o Terraform basada en tu iac seleccionado. Puedes usar esto para desplegar tu FastAPI.

CDK

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

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

Esto configura:

1. Una función AWS Lambda para cada operación en la aplicación FastAPI
2. API Gateway HTTP/REST API como disparador de la función
3. Roles y permisos de IAM
4. Grupo de logs de CloudWatch
5. Configuración de trazado de X-Ray
6. Espacio de nombres de métricas de CloudWatch

Configuración CORS de CDK

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 AWS Lambda API para APIs HTTP / REST. Puedes llamar al método restrictCorsTo de la API con constructos de sitio 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 se puede generar usando el generador ts#website

auth = cognito

Autenticación Cognito

Si seleccionaste usar autenticación Cognito, necesitarás proporcionar 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 se puede generar usando el generador ts#website#auth

auth = custom

Lambda Authorizer Personalizado

Cuando se usa autenticación Custom, el constructo crea un Lambda Authorizer internamente desde el archivo authorizer.py generado, que deniega todas las solicitudes por defecto. Debes implementar tu lógica de autorización en ese archivo antes de que tu API acepte cualquier tráfico.

Terraform

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

El módulo de API almacena su zip de despliegue de Lambda en un bucket S3 de activos compartido — consulta la guía de infraestructura de Terraform para más detalles. Instancia el módulo core/asset-bucket una vez por despliegue y pasa su salida bucket_name a cada módulo de API / Lambda a través de la entrada asset_bucket_name:

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
}

Esto configura:

1. Una función AWS Lambda que sirve todas las rutas de FastAPI
2. API Gateway HTTP/REST API como disparador de la función
3. Roles y permisos de IAM
4. Grupo de logs de CloudWatch
5. Configuración de trazado de X-Ray
6. Configuración de CORS

Configuración CORS de Terraform

Si tu solución incluye un módulo de sitio web de Terraform, entonces puedes 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 desplegar tu API agrega

• una propiedad cors_allow_origins, establecida en ["http://localhost:4200", "http://localhost:4300", "https://<domain name>"], para APIs HTTP. Esto restringe el CORS del API gateway a esta distribución y localhost.
• 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 localhost) en las integraciones de AWS Lambda. Ten 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 solución de esto.

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

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

auth = cognito

Autenticación Cognito

Si seleccionaste usar autenticación Cognito, necesitarás proporcionar la configuración de Cognito:

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
}

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

El módulo de Terraform proporciona varias salidas que puedes usar:

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

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

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
}

auth = custom

Lambda Authorizer Personalizado

Cuando se usa autenticación Custom, tu API está protegida por un Lambda Authorizer que deniega todas las solicitudes por defecto. Debes implementar tu lógica de autorización en el archivo authorizer.py generado antes de que tu API acepte cualquier tráfico.

infra = rest-lambda

WAF

Para las API REST, el constructo generado asocia una Web ACL de AWS WAFv2 con la etapa de API Gateway de forma predeterminada. La Web ACL utiliza el conjunto de reglas predeterminado administrado por AWS (AWSManagedRulesCommonRuleSet y AWSManagedRulesKnownBadInputsRuleSet), proporcionando protección contra exploits web comunes, incluidos los OWASP Top 10. Los registros de solicitudes de WAF se escriben en un grupo de CloudWatch Logs.

Desviación de SizeRestrictions_BODY de los valores predeterminados

La regla SizeRestrictions_BODY de AWSManagedRulesCommonRuleSet se anula a Count en lugar de Block, ya que el límite de 8 KB de la regla es demasiado restrictivo para la mayoría de las API. Las solicitudes de gran tamaño aún se registrarán como métricas para que puedas monitorearlas. Consulta la guía de límites de tamaño del cuerpo de AWS WAF para obtener más detalles. API Gateway aplica de forma nativa su tamaño máximo de carga útil de 10 MB, devolviendo un 413 para solicitudes más grandes.

Puedes editar el constructo rest-api generado para agregar, eliminar o ajustar reglas (por ejemplo, para agregar reglas basadas en tasa o grupos de reglas administradas adicionales).

CDK

Para optar por no participar (por ejemplo, para adjuntar tu propia Web ACL), establece enableWaf en false:

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

Terraform

Para optar por no participar (por ejemplo, para adjuntar tu propia Web ACL), establece enable_waf en false:

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

  asset_bucket_name = module.asset_bucket.bucket_name
  enable_waf        = false
}

infra = rest-lambda

Registro de acceso

Para las REST APIs, la infraestructura generada habilita el registro de acceso de forma predeterminada, escribiendo una línea JSON estructurada por solicitud en un grupo de CloudWatch Logs dedicado. El grupo de logs está cifrado con una clave KMS administrada por el cliente y se retiene durante un año.

API Gateway escribe los logs de acceso utilizando un rol de CloudWatch Logs a nivel de cuenta. Este rol se configura en la configuración AWS::ApiGateway::Account, que es un singleton por región por cuenta: solo hay un rol para cada REST API en la región. Para gestionar esto de forma segura en múltiples stacks implementados de forma independiente, la infraestructura generada:

• Crea un rol compartido de CloudWatch Logs y lo configura en la cuenta solo cuando no hay un rol funcional ya establecido, por lo que las implementaciones nunca sobrescriben un rol que pertenece a otro stack.
• Deja la configuración de la cuenta intacta durante el desmontaje, por lo que destruir un stack nunca deshabilita el registro para otras REST APIs en la región.

CDK

El rol de cuenta es gestionado por el constructo ApiGatewayAccount, un singleton con ámbito de stack resuelto mediante ApiGatewayAccount.ensure(scope). La etapa de cada REST API depende de él, y el rol se configura mediante un recurso personalizado respaldado por Lambda.

El formato del log de acceso es establecido por el constructo RestApi que tu API extiende. Para personalizarlo, pasa deployOptions a super en el archivo generado packages/common/constructs/src/app/apis/my-api.ts, manteniendo el tracingEnabled que el constructo ya establece:

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

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

AccessLogFormat se importa desde aws-cdk-lib/aws-apigateway. Cualquier cosa que dejes sin configurar mantiene el valor predeterminado del constructo: un formato JSON con los campos estándar.

Terraform

El rol de cuenta es gestionado por el módulo core/api/api-gateway-account, que es instanciado por el módulo de API generado. Configura la cuenta de forma idempotente y nunca se restablece con terraform destroy.

Puedes personalizar el formato del log de acceso editando el bloque access_log_settings en el recurso aws_api_gateway_stage en el módulo de API generado.

Integraciones

Los constructos CDK de API REST/HTTP están configurados para proporcionar una interfaz con seguridad de tipos para definir integraciones para cada una de sus operaciones.

CDK

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

Terraform

Patrón de Enrutador

Los módulos Terraform utilizan el “patrón de enrutador” con una única función Lambda que sirve todas las operaciones. Las integraciones con seguridad de tipos no son compatibles - el módulo crea una función Lambda que maneja todas las solicitudes de API.

Para integraciones explícitas por operación con Terraform, necesitaría crear manualmente funciones Lambda individuales y rutas de API Gateway. Consulte la sección Integraciones Explícitas para ver ejemplos.

Integraciones Predeterminadas

CDK

Puede usar el método estático defaultIntegrations para hacer uso del patrón predeterminado, que define una función AWS Lambda individual para cada operación:

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

Terraform

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

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

  asset_bucket_name = module.asset_bucket.bucket_name

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

Acceso a Integraciones

CDK

Puede acceder a las funciones AWS Lambda subyacentes a través de la propiedad integrations del constructo de API, de manera segura en cuanto a tipos. Por ejemplo, si su API define una operación llamada sayHello y necesita agregar algunos permisos a esta función, puede hacerlo de la siguiente manera:

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

Si su API utiliza el patrón shared, el enrutador 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');

Terraform

Con el patrón de enrutador de Terraform, solo hay una función Lambda. Puede acceder a ella a través de las salidas del módulo:

# 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/*"
      }
    ]
  })
}

Personalización de Opciones Predeterminadas

CDK

Si desea personalizar las opciones utilizadas al crear la función Lambda para cada integración predeterminada, puede usar el método withDefaultOptions. Por ejemplo, si desea que todas sus funciones Lambda residan en una Vpc:

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

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

Terraform

La configuración de VPC ya es compatible con el módulo generado — establezca enable_vpc junto con vpc_id y subnet_ids, y el módulo desplegará la función Lambda en su VPC detrás de un grupo de seguridad que crea para usted:

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
}

Para opciones que el módulo no expone, edite el recurso aws_lambda_function en el módulo Terraform generado directamente.

Personalización de Opciones por Operación

CDK

Para personalizar las opciones utilizadas para crear la integración predeterminada para operaciones específicas (sin afectar a las demás), puede usar el método withOperationOptions. Por ejemplo, si desea aumentar el tiempo de espera de la función Lambda para solo una operación:

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

Las opciones que especifique se fusionan con las opciones de integración predeterminadas (y cualquier opción establecida a través de withDefaultOptions). Tenga en cuenta que no puede especificar opciones para operaciones que haya reemplazado a través de withOverrides, ya que estas ya no usan la integración predeterminada.

Encontrará un error de tipo si la misma operación es objetivo tanto de withOperationOptions como de withOverrides, independientemente del orden en que los llame.

Terraform

Para personalizar opciones para operaciones específicas con Terraform, necesita editar el módulo Terraform generado para configurar funciones Lambda individuales por operación (consulte la sección Integraciones Explícitas a continuación).

Anulación de Integraciones

CDK

También puede anular integraciones para operaciones específicas usando el método withOverrides. Cada anulación 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 seguro en cuanto a tipos. Por ejemplo, si desea anular una API getDocumentation para que apunte a documentación alojada por algún sitio web externo, podría lograrlo de la siguiente manera:

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

También notará que la integración anulada ya no tiene una propiedad handler al acceder a ella a través de api.integrations.getDocumentation.

Puede agregar propiedades adicionales a una integración que también se tipará en consecuencia, permitiendo que otros tipos de integración se abstraigan pero permanezcan seguros en cuanto a tipos, por ejemplo, si ha creado una integración S3 para una API REST y luego desea hacer referencia al bucket para una operación en particular, puede hacerlo de la siguiente manera:

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

Anulaciones de Integración

La anulación de integraciones específicas no es compatible con los módulos Terraform ya que utilizan el patrón de enrutador. Todas las operaciones son manejadas por la única función Lambda.

Para diferentes tipos de integración por operación, necesitaría implementar integraciones explícitas manualmente (consulte la sección Integraciones Explícitas a continuación).

Anulación de Autorizadores

CDK

También puede proporcionar options en su integración para anular opciones de método particulares como autorizadores, por ejemplo, si desea usar autenticación Cognito para su operación getDocumentation:

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

Anulaciones de Autorizador

Las anulaciones de autorizador por operación no son compatibles con los módulos Terraform. Toda la API utiliza el método de autenticación especificado al generar la API (IAM, Cognito o Custom).

Para autorización por operación, necesitaría implementar integraciones explícitas manualmente como se muestra a continuación.

Integraciones Explícitas

CDK

Si lo prefiere, puede optar por no usar las integraciones predeterminadas y en su lugar proporcionar directamente una para cada operación. Esto es útil si, por ejemplo, cada operación necesita usar un tipo diferente de integración o si desea recibir un error de tipo al agregar nuevas operaciones:

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

Terraform

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

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

1. Elimine las rutas proxy predeterminadas (por ejemplo, resource "aws_apigatewayv2_route" "proxy_routes")
2. Reemplace la única función Lambda con funciones individuales para cada operación
3. Cree integraciones y rutas específicas para cada operación, reutilizando el mismo paquete ZIP:

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" {
   s3_bucket         = aws_s3_object.lambda_zip.bucket
   s3_key            = aws_s3_object.lambda_zip.key
   s3_object_version = aws_s3_object.lambda_zip.version_id
   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" {
   s3_bucket         = aws_s3_object.lambda_zip.bucket
   s3_key            = aws_s3_object.lambda_zip.key
   s3_object_version = aws_s3_object.lambda_zip.version_id
   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 = var.env
   }

   tags = var.tags
 }

 resource "aws_lambda_function" "get_documentation_handler" {
   s3_bucket         = aws_s3_object.lambda_zip.bucket
   s3_key            = aws_s3_object.lambda_zip.key
   s3_object_version = aws_s3_object.lambda_zip.version_id
   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 = 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" {
   s3_bucket         = aws_s3_object.lambda_zip.bucket
   s3_key            = aws_s3_object.lambda_zip.key
   s3_object_version = aws_s3_object.lambda_zip.version_id
   function_name    = "MyApiHandler-${random_string.suffix.result}"
   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_api_gateway_integration" "lambda_integration" {
   rest_api_id = module.rest_api.api_id
   resource_id = aws_api_gateway_resource.proxy_resource.id
   http_method = aws_api_gateway_method.proxy_method.http_method
   integration_http_method = "POST"
   type                    = "AWS_PROXY"
   uri                     = aws_lambda_function.api_lambda.invoke_arn
   # ... rest of configuration
 }

# Remove the default catch-all proxy method
 resource "aws_api_gateway_method" "proxy_method" {
   rest_api_id   = module.rest_api.api_id
   resource_id   = aws_api_gateway_resource.proxy_resource.id
   http_method   = "ANY"
   # ... rest of configuration
 }

# Add individual Lambda functions for each operation using the same bundle
 resource "aws_lambda_function" "say_hello_handler" {
   s3_bucket         = aws_s3_object.lambda_zip.bucket
   s3_key            = aws_s3_object.lambda_zip.key
   s3_object_version = aws_s3_object.lambda_zip.version_id
   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 = var.env
   }

   tags = var.tags
 }

 resource "aws_lambda_function" "get_documentation_handler" {
   s3_bucket         = aws_s3_object.lambda_zip.bucket
   s3_key            = aws_s3_object.lambda_zip.key
   s3_object_version = aws_s3_object.lambda_zip.version_id
   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 = 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}/*/*"
 }

Patrón de Integración

CDK

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 predeterminado para las API generadas.
• shared crea un único enrutador Lambda predeterminado y lo reutiliza para cada operación a menos que anule integraciones específicas.

isolated le brinda permisos y configuración más detallados por operación. shared reduce la proliferación de Lambda y la integración de API Gateway mientras permite anulaciones selectivas.

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

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

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

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

Terraform

Los módulos Terraform utilizan automáticamente el patrón de enrutador - este es el enfoque predeterminado y el único compatible. El módulo generado crea una única función Lambda que maneja todas las operaciones de API.

Simplemente puede instanciar el módulo predeterminado para obtener el patrón de enrutador:

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

  asset_bucket_name = module.asset_bucket.bucket_name

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

Generación de Código

CDK

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

Se agrega un objetivo 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 compilación, se ignora en el control de versiones.

Compilar Antes de Desplegar

Necesitarás ejecutar una compilación cada vez que cambies tu API para asegurar que los tipos consumidos por el constructo CDK estén actualizados.

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Recarga en Caliente

Si estás trabajando activamente tanto en tu infraestructura CDK como en FastAPI juntos, puedes usar nx watch para regenerar estos tipos cada vez que hagas cambios en la API:

pnpm

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

yarn

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

npm

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

bun

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

Terraform

Limitaciones de Terraform

No admitimos integraciones con seguridad de tipos para Terraform, y por lo tanto no se configuran objetivos de generación de código si seleccionaste Terraform para tu iac.

auth = iam

Conceder Acceso (Solo IAM)

Si seleccionaste usar autenticación IAM, puedes usar el método grantInvokeAccess para conceder acceso a tu 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
}

Las salidas clave del módulo de API que puedes usar para políticas de 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

pnpm nx serve my-api

yarn

yarn nx serve my-api

npm

npx nx serve my-api

bun

bunx nx serve my-api

Esto inicia un servidor de desarrollo local de FastAPI con:

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

Invocar tu FastAPI

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

Conexiones

Usa el generador connection para integrar este proyecto con otros en tu espacio de trabajo. Las siguientes conexiones involucran este proyecto:

React a FastAPILlamar a una FastAPI de Python desde un sitio web React

FastAPI a Python DynamoDBConectar una FastAPI a una tabla DynamoDB