FastAPI

FastAPI è un framework per la creazione di API in Python.

Il generatore FastAPI crea una nuova applicazione FastAPI con configurazione dell’infrastruttura AWS CDK o Terraform. Il backend generato utilizza AWS Lambda per il deployment serverless, esposto tramite un’API AWS API Gateway. Configura AWS Lambda Powertools per l’osservabilità, inclusi logging, tracciamento AWS X-Ray e metriche Cloudwatch.

Utilizzo

Generare una FastAPI

Puoi generare una nuova FastAPI in due modi:

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - py#api
5. Compila i parametri richiesti
   • framework: fastapi
6. Clicca su Generate

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	Nome del progetto API da generare
framework	fastapi	fastapi	Il framework API da utilizzare.
integrationPattern	isolated | shared	isolated	Come vengono generate le integrazioni API Gateway per l'API. Scegli tra isolated (predefinito) e shared.
auth	iam | cognito | custom	iam	Il metodo utilizzato per autenticare con la tua API. Scegli tra iam (predefinito), cognito o custom.
directory	string	packages	La directory in cui memorizzare l'applicazione.
subDirectory	string	-	La sottodirectory in cui viene posizionato il progetto. Per impostazione predefinita corrisponde al nome del progetto.
iac	inherit | cdk | terraform	inherit	Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.
moduleName	string	-	Nome del modulo Python
infra	rest-lambda | http-lambda | none	rest-lambda	Il tipo di infrastruttura da utilizzare per distribuire questa API.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Scelta del tipo di API

Puoi scegliere tra una REST API o una HTTP API per distribuire la tua API. Fai riferimento alla API Gateway Developer Guide per aiutarti a decidere.

Tipo di API

Seleziona rest-lambda (predefinito) come infra se intendi implementare operazioni di streaming.

Pattern di integrazione

L’opzione integrationPattern è impostata su isolated per impostazione predefinita, che crea una Lambda per ogni operazione FastAPI. Seleziona shared se preferisci un singolo handler Lambda condiviso per l’intera API, con override opzionali per operazione.

Output del Generatore

Il generatore creerà la seguente struttura del progetto nella directory <directory>/<api-name>:

• project.json Configurazione del progetto e target di build
• pyproject.toml Configurazione del progetto Python e dipendenze
• run.sh Script di bootstrap Lambda Web Adapter per avviare l’app FastAPI tramite uvicorn
• Directory<module_name>

  • __init__.py Inizializzazione del modulo
  • init.py Configura l’app FastAPI e il middleware powertools
  • main.py Implementazione dell’API
• Directoryscripts

  • generate_open_api.py Script per generare uno schema OpenAPI dall’app FastAPI

Infrastruttura

Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iacProvider selezionato, creerà un progetto in packages/common che include i relativi costrutti CDK o moduli Terraform.

Il progetto comune di infrastruttura come codice è strutturato come segue:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Construct per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Construct generici riutilizzati dai construct in app

      • …
    • index.ts Punto di ingresso che esporta i construct da app
  • project.json Target di build e configurazione del progetto

Progetto generato

Questo progetto è generato utilizzando il ts#project generator e quindi configura gli stessi target di build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Moduli Terraform per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Moduli generici riutilizzati dai moduli in app

      • …
  • project.json Target di build e configurazione del progetto

Progetto generato

Questo progetto è generato utilizzando il terraform#project generator e quindi configura gli stessi target di build.

Per la distribuzione della tua API, vengono generati i seguenti file:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directoryapis

      • <project-name>.ts Costrutto CDK per distribuire la tua API
  • Directorycore

    • Directoryapi

      • http-api.ts Costrutto CDK per distribuire un’API HTTP (se hai scelto di distribuire un’API HTTP)
      • rest-api.ts Costrutto CDK per distribuire un’API REST (se hai scelto di distribuire un’API REST)
      • utils.ts Utilities per i costrutti API

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directoryapis

      • Directory<project-name>

        • <project-name>.tf Modulo per distribuire la tua API
  • Directorycore

    • Directoryapi

      • Directoryhttp-api

        • http-api.tf Modulo per distribuire un’API HTTP (se hai scelto di distribuire un’API HTTP)
      • Directoryrest-api

        • rest-api.tf Modulo per distribuire un’API REST (se hai scelto di distribuire un’API REST)

Architettura

L’applicazione distribuita ha la seguente architettura:

REST API

Le REST API includono un Web ACL AWS WAFv2 davanti allo stage di API Gateway con il set di regole predefinito gestito da AWS abilitato.

HTTP API

Le HTTP API non supportano direttamente WAF — se hai bisogno della protezione WAF, scegli REST API oppure posiziona l’HTTP API dietro una distribuzione CloudFront.

Implementare la tua FastAPI

L’implementazione principale dell’API si trova in main.py. Qui è dove definisci le route API e le relative implementazioni. Ecco un esempio:

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

Il generatore configura automaticamente diverse funzionalità:

1. Integrazione con AWS Lambda Powertools per l’osservabilità
2. Middleware per la gestione degli errori
3. Correlazione richiesta/risposta
4. Raccolta delle metriche
5. Deployment AWS Lambda tramite Lambda Web Adapter con uvicorn
6. Streaming type-safe (solo REST API)

Osservabilità con AWS Lambda Powertools

Logging

Il generatore configura il logging strutturato utilizzando AWS Lambda Powertools. Puoi accedere al logger nei tuoi route handler:

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}

Il logger include automaticamente:

• ID di correlazione per il tracciamento delle richieste
• Percorso e metodo della richiesta
• Informazioni sul contesto Lambda
• Indicatori di cold start

Tracciamento

Il tracciamento AWS X-Ray è configurato automaticamente. Puoi aggiungere sottosegmenti personalizzati ai tuoi trace:

from .init import app, tracer

@app.get("/items/{item_id}")
@tracer.capture_method
def read_item(item_id: int):
    # Crea un nuovo sottosegmento
    with tracer.provider.in_subsegment("fetch-item-details"):
        # La tua logica qui
        return {"item_id": item_id}

Metriche

Le metriche CloudWatch vengono raccolte automaticamente per ogni richiesta. Puoi aggiungere metriche personalizzate:

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}

Le metriche predefinite includono:

• Conteggio delle richieste
• Conteggio successi/fallimenti
• Metriche sui cold start
• Metriche per route specifica

Gestione degli Errori

Il generatore include una gestione degli errori completa:

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}

Le eccezioni non gestite vengono intercettate dal middleware e:

1. Registrano l’eccezione completa con stack trace
2. Registrano una metrica di fallimento
3. Restituiscono una risposta sicura 500 al client
4. Mantengono l’ID di correlazione

Modelli di risposta

Si consiglia di specificare i modelli di risposta per le operazioni API per una migliore generazione del codice se si utilizza il generatore connection. Vedi qui per maggiori dettagli.

Accesso all’Utente Chiamante

Quando la tua API è protetta da autenticazione, i tuoi route handler spesso devono sapere chi sta chiamando. La FastAPI generata viene eseguita all’interno di AWS Lambda tramite il Lambda Web Adapter, che inoltra il contesto della richiesta API Gateway come JSON nell’header x-amzn-request-context. Puoi leggerlo dalla Request di FastAPI per estrarre l’identità del chiamante.

Come esempio, aggiungiamo un endpoint /me che restituisce dettagli sull’utente chiamante. Implementeremo l’estrazione come una dipendenza FastAPI in modo che possa essere riutilizzata tra le route. La forma del contesto della richiesta — e quindi come estrai l’identità — dipende sia dal metodo auth selezionato che dal fatto che tu abbia distribuito una REST API o HTTP API.

auth = iam

Per l’autenticazione IAM, cerchiamo il chiamante in Cognito utilizzando il sub estratto dal contesto della richiesta API Gateway. Crea identity.py accanto 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:
    # Il Lambda Web Adapter inoltra il contesto della richiesta API Gateway come 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(
        # Assume che l'id del user pool sia configurato nell'ambiente lambda
        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:
    # Il Lambda Web Adapter inoltra il contesto della richiesta API Gateway come 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(
        # Assume che l'id del user pool sia configurato nell'ambiente lambda
        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', l’authorizer Cognito User Pools di API Gateway verifica il JWT che il chiamante fornisce nell’header Authorization e posiziona i claim verificati sul contesto della richiesta.

Crea identity.py accanto 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:
    # Il Lambda Web Adapter inoltra il contesto della richiesta API Gateway come 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

Le HTTP API utilizzano un authorizer JWT che posiziona i claim verificati sotto 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:
    # Il Lambda Web Adapter inoltra il contesto della richiesta API Gateway come 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)]

Nessuna verifica del token richiesta

Non hai bisogno di alcuna libreria di verifica JWT qui — l’authorizer Cognito User Pools di API Gateway ha già verificato la firma, l’emittente, gli scope e la scadenza prima che la tua Lambda venga eseguita. Se uno di questi controlli fallisce, API Gateway restituisce 401 Unauthorized e il tuo handler non viene mai invocato.

Puoi quindi iniettare la dipendenza CurrentUser in qualsiasi route che necessita dell’identità del chiamante:

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 generata supporta risposte in streaming out of the box quando si utilizza una REST API. L’infrastruttura è configurata per utilizzare AWS Lambda Web Adapter per eseguire la tua FastAPI tramite uvicorn all’interno di Lambda, con ResponseTransferMode.STREAM in API Gateway per tutte le operazioni REST API, il che consente allo streaming di funzionare insieme alle operazioni non in streaming.

Utilizzo di JsonStreamingResponse

Il file init.py generato esporta una classe JsonStreamingResponse che fornisce streaming type-safe con una corretta generazione dello schema OpenAPI. Ciò garantisce che il generatore connection possa produrre metodi client di streaming correttamente tipizzati.

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 classe JsonStreamingResponse:

1. Serializza i modelli Pydantic nel formato JSON Lines (application/jsonl)
2. Fornisce un helper openapi_response che genera lo schema OpenAPI corretto con itemSchema, consentendo al generatore connection di produrre metodi client di streaming type-safe

Consumo

Per consumare uno stream di risposte, puoi utilizzare il generatore connection che fornirà un metodo type-safe per iterare sui chunk dello stream.

Distribuire la tua FastAPI

Il generatore FastAPI crea infrastruttura come codice CDK o Terraform in base al iacProvider selezionato. Puoi utilizzarlo per distribuire la tua FastAPI.

CDK

Il costrutto CDK per distribuire la tua API si trova nella cartella common/constructs. Puoi usarlo in un’applicazione CDK:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Aggiungi l'API allo stack
    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Questo configura:

1. Una funzione AWS Lambda per ogni operazione nell’applicazione FastAPI
2. API Gateway HTTP/REST API come trigger della funzione
3. Ruoli e permessi IAM
4. Log group CloudWatch
5. Configurazione del tracciamento X-Ray
6. Namespace per le metriche CloudWatch

Configurazione CORS CDK

Se la tua soluzione include un sito web, puoi configurare la sua distribuzione CloudFront come unica origine CORS consentita nelle integrazioni API gateway / API AWS Lambda per le API HTTP / REST. Puoi chiamare il metodo restrictCorsTo dell’API con costrutti di siti web, distribuzioni CloudFront, stringhe di origine, o una combinazione di essi.

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

Il costrutto MyWebsite può essere generato utilizzando il generatore ts#website

auth = cognito

Autenticazione Cognito

Se hai selezionato l’autenticazione Cognito, dovrai fornire la proprietà identity al costrutto 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,
    });
  }
}

Il costrutto UserIdentity può essere generato utilizzando il generatore ts#website#auth

auth = custom

Custom Lambda Authorizer

When using Custom auth, the construct creates a Lambda Authorizer internally from the generated authorizer.py file, which denies all requests by default. You must implement your authorization logic in that file before your API will accept any traffic.

Terraform

I moduli Terraform per distribuire la tua API si trovano nella cartella common/terraform. Puoi usarli in una configurazione Terraform.

Il modulo API carica il suo zip di deployment Lambda in un bucket S3 condiviso per gli asset — vedi la guida all’infrastruttura Terraform per i dettagli. Istanzia il modulo core/asset-bucket una volta per deployment e passa il suo output bucket_name in ogni modulo API / Lambda tramite l’input 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

  # Variabili d'ambiente per la funzione Lambda
  env = {
    ENVIRONMENT = var.environment
    LOG_LEVEL   = "INFO"
  }

  # Policy IAM aggiuntive se necessarie
  additional_iam_policy_statements = [
    # Aggiungi eventuali permessi aggiuntivi richiesti dalla tua API
  ]

  tags = local.common_tags
}

Questo configura:

1. Una funzione AWS Lambda che serve tutte le route FastAPI
2. API Gateway HTTP/REST API come trigger della funzione
3. Ruoli e permessi IAM
4. Log group CloudWatch
5. Configurazione del tracciamento X-Ray
6. Configurazione CORS

Configurazione CORS Terraform

Se la tua soluzione include un modulo Terraform per il sito web, puoi utilizzare il suo nome di dominio CloudFront per limitare CORS. Dato un nome di dominio CloudFront <domain_name>, all’interno del modulo Terraform per il deployment della tua API aggiungi

• una proprietà cors_allow_origins, impostata a ["http://localhost:4200", "http://localhost:4300", "https://<domain name>"], per le API HTTP. Questo limita il CORS dell’API gateway a questa distribuzione e al local host.
• una variabile d’ambiente ALLOWED_ORIGINS, impostata a "https://<domain_name>", per le API REST. Questo imposta la distribuzione CloudFront come unica origine CORS consentita (oltre al local host) nelle integrazioni AWS Lambda. Nota che questa restrizione non viene applicata al preflight OPTIONS - per favore metti +1 a questa issue su GitHub per aiutare a dare priorità alla risoluzione di questo problema.

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

Il costrutto MyWebsite può essere generato utilizzando il generatore ts#website

auth = cognito

Autenticazione Cognito

Se hai selezionato l’autenticazione Cognito, dovrai fornire la configurazione 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
}

Puoi configurare User Pool e Client Cognito utilizzando le risorse o moduli Terraform appropriati.

Il modulo Terraform fornisce diversi output utilizzabili:

# Accedi all'endpoint API
output "api_url" {
  value = module.my_api.stage_invoke_url
}

# Accedi ai dettagli della funzione Lambda
output "lambda_function_name" {
  value = module.my_api.lambda_function_name
}

# Accedi al ruolo IAM per concedere permessi aggiuntivi
output "lambda_execution_role_arn" {
  value = module.my_api.lambda_execution_role_arn
}

Puoi personalizzare le impostazioni CORS passando variabili al modulo:

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

  asset_bucket_name = module.asset_bucket.bucket_name

  # Configurazione CORS personalizzata
  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

Custom Lambda Authorizer

When using Custom auth, your API is protected by a Lambda Authorizer that denies all requests by default. You must implement your authorization logic in the generated authorizer.py file before your API will accept any traffic.

infra = rest-lambda

WAF

Per le API REST, il costrutto generato associa di default una Web ACL AWS WAFv2 allo stage di API Gateway. La Web ACL utilizza il ruleset predefinito gestito da AWS (AWSManagedRulesCommonRuleSet e AWSManagedRulesKnownBadInputsRuleSet), fornendo protezione contro exploit web comuni inclusa la OWASP Top 10. I log delle richieste WAF vengono scritti in un gruppo CloudWatch Logs.

Deviazione di SizeRestrictions_BODY dai valori predefiniti

La regola SizeRestrictions_BODY di AWSManagedRulesCommonRuleSet viene sovrascritta su Count anziché Block, poiché il limite di 8 KB della regola è troppo restrittivo per la maggior parte delle API. Le richieste di dimensioni eccessive verranno comunque registrate come metriche in modo da poterle monitorare. Consulta la guida AWS WAF body size limits per maggiori dettagli. API Gateway applica nativamente la sua dimensione massima del payload di 10 MB, restituendo un 413 per richieste più grandi.

Puoi modificare il costrutto rest-api generato per aggiungere, rimuovere o regolare le regole (ad esempio, per aggiungere regole basate sulla frequenza o gruppi di regole gestite aggiuntivi).

CDK

Per disattivare (ad esempio, per collegare la tua Web ACL), imposta enableWaf su false:

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

Terraform

Per disattivare (ad esempio, per collegare la tua Web ACL), imposta enable_waf su 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

Access logging

Per le REST API, l’infrastruttura generata abilita la registrazione degli accessi per impostazione predefinita, scrivendo una riga JSON strutturata per richiesta in un gruppo CloudWatch Logs dedicato. Il gruppo di log è crittografato con una chiave KMS gestita dal cliente e conservato per un anno.

API Gateway scrive i log di accesso utilizzando un ruolo CloudWatch Logs a livello di account. Questo ruolo è configurato nell’impostazione AWS::ApiGateway::Account, che è un singleton per regione per account — esiste un solo ruolo per ogni REST API nella regione. Per gestire questo in modo sicuro tra più stack distribuiti indipendentemente, l’infrastruttura generata:

• Crea un ruolo CloudWatch Logs condiviso e lo configura sull’account solo quando non è già impostato un ruolo funzionante, in modo che le distribuzioni non sovrascrivano mai un ruolo di proprietà di un altro stack.
• Lascia l’impostazione dell’account intatta durante la rimozione, in modo che la distruzione di uno stack non disabiliti mai la registrazione per altre REST API nella regione.

CDK

Il ruolo dell’account è gestito dal costrutto ApiGatewayAccount, un singleton con ambito stack risolto tramite ApiGatewayAccount.ensure(scope). Ogni stage della REST API dipende da esso e il ruolo è configurato da una risorsa personalizzata supportata da Lambda.

Puoi personalizzare il formato del log di accesso passando deployOptions durante la costruzione della tua API:

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

Terraform

Il ruolo dell’account è gestito dal modulo core/api/api-gateway-account, che viene istanziato dal modulo API generato. Configura l’account in modo idempotente e non viene mai reimpostato con terraform destroy.

Puoi personalizzare il formato del log di accesso modificando il blocco access_log_settings sulla risorsa aws_api_gateway_stage nel modulo API generato.

Integrazioni

I costrutti CDK per le API REST/HTTP sono configurati per fornire un’interfaccia type-safe per definire le integrazioni per ciascuna delle tue operazioni.

CDK

I costrutti CDK forniscono supporto completo per l’integrazione type-safe come descritto di seguito.

Terraform

Pattern del router

I moduli Terraform utilizzano il “router pattern” con una singola funzione Lambda che gestisce tutte le operazioni. Le integrazioni type-safe non sono supportate - il modulo crea un’unica funzione Lambda che elabora tutte le richieste API.

Per integrazioni esplicite per operazione con Terraform, dovresti creare manualmente singole funzioni Lambda e route API Gateway. Vedi la sezione Integrazioni Esplicite per esempi.

Integrazioni Predefinite

CDK

Puoi utilizzare il metodo statico defaultIntegrations per sfruttare il pattern predefinito, che definisce una singola funzione AWS Lambda per ogni operazione:

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

Terraform

I moduli Terraform utilizzano automaticamente il router pattern con una singola funzione Lambda. Nessuna configurazione aggiuntiva è necessaria:

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

  asset_bucket_name = module.asset_bucket.bucket_name

  # Il modulo crea automaticamente una singola funzione Lambda
  # che gestisce tutte le operazioni API
  tags = local.common_tags
}

Accesso alle Integrazioni

CDK

Puoi accedere alle funzioni AWS Lambda sottostanti tramite la proprietà integrations del costrutto API in modo type-safe. Ad esempio, se la tua API definisce un’operazione chiamata sayHello e devi aggiungere dei permessi a questa funzione, puoi farlo come segue:

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

// sayHello è tipizzato in base alle operazioni definite nella tua API
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
  effect: Effect.ALLOW,
  actions: [...],
  resources: [...],
}));

Se la tua API utilizza il pattern shared, il router Lambda condiviso è esposto come api.integrations.$router:

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

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

Terraform

Con il router pattern di Terraform, esiste solo una funzione Lambda. Puoi accedervi tramite gli output del modulo:

# Concedi permessi aggiuntivi alla singola funzione 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/*"
      }
    ]
  })
}

Personalizzazione delle Opzioni Predefinite

CDK

Se desideri personalizzare le opzioni utilizzate durante la creazione delle funzioni Lambda per ogni integrazione predefinita, puoi usare il metodo withDefaultOptions. Ad esempio, per far risiedere tutte le funzioni Lambda in una VPC:

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

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

Terraform

Per personalizzare opzioni come la configurazione VPC, devi modificare il modulo Terraform generato. Ad esempio, per aggiungere il supporto VPC a tutte le funzioni Lambda:

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

# Aggiungi variabili VPC
variable "vpc_subnet_ids" {
  description = "Lista di ID subnet VPC per la funzione Lambda"
  type        = list(string)
  default     = []
}

variable "vpc_security_group_ids" {
  description = "Lista di ID security group VPC per la funzione Lambda"
  type        = list(string)
  default     = []
}

# Aggiorna la risorsa Lambda function
resource "aws_lambda_function" "api_lambda" {
  # ... configurazione esistente ...

  # Aggiungi configurazione VPC
  vpc_config {
    subnet_ids         = var.vpc_subnet_ids
    security_group_ids = var.vpc_security_group_ids
  }
}

Quindi utilizza il modulo con la configurazione VPC:

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

  asset_bucket_name = module.asset_bucket.bucket_name

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

Personalizzazione delle Opzioni per Operazione

CDK

Per personalizzare le opzioni utilizzate per creare l’integrazione predefinita per operazioni specifiche (senza influenzare le altre), puoi usare il metodo withOperationOptions. Ad esempio, se desideri aumentare il timeout della funzione Lambda per una sola operazione:

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

// Le operazioni selezionate rimangono integrazioni predefinite, quindi sono ancora tipizzate di conseguenza:
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({ ... }));

Le opzioni che specifichi vengono unite alle opzioni di integrazione predefinite (e a qualsiasi opzione impostata tramite withDefaultOptions). Nota che non puoi specificare opzioni per operazioni che hai sostituito tramite withOverrides, poiché queste non utilizzano più l’integrazione predefinita.

Incontrerai un errore di tipo se la stessa operazione è targetizzata sia da withOperationOptions che da withOverrides, indipendentemente dall’ordine in cui li chiami.

Terraform

Per personalizzare le opzioni per operazioni specifiche con Terraform, devi modificare il modulo Terraform generato per configurare singole funzioni Lambda per operazione (vedi la sezione Integrazioni Esplicite di seguito).

Override delle Integrazioni

CDK

Puoi anche sovrascrivere le integrazioni per operazioni specifiche usando il metodo withOverrides. Ogni override deve specificare una proprietà integration tipizzata correttamente per il costrutto di integrazione CDK appropriato per l’API HTTP o REST. Il metodo withOverrides è anch’esso type-safe. Ad esempio, se desideri sovrascrivere un’API getDocumentation per puntare alla documentazione ospitata da un sito web esterno, puoi farlo come segue:

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

Noterai anche che l’integrazione sovrascritta non ha più una proprietà handler quando vi si accede tramite api.integrations.getDocumentation.

Puoi aggiungere proprietà aggiuntive a un’integrazione che saranno anche tipizzate di conseguenza, consentendo ad altri tipi di integrazione di essere astratti ma rimanere type-safe, ad esempio se hai creato un’integrazione S3 per un’API REST e successivamente desideri fare riferimento al bucket per una particolare operazione, puoi farlo come segue:

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

// Successivamente, magari in un altro file, puoi accedere alla proprietà bucket che abbiamo definito
// in modo type-safe
api.integrations.getFile.bucket.grantRead(...);

Terraform

Override di integrazione

L’override di integrazioni specifiche non è supportato con i moduli Terraform poiché utilizzano il router pattern. Tutte le operazioni sono gestite dalla singola funzione Lambda.

Per tipi di integrazione diversi per operazione, dovresti implementare manualmente integrazioni esplicite (vedi la sezione Integrazioni Esplicite di seguito).

Override degli Authorizer

CDK

Puoi anche fornire options nella tua integrazione per sovrascrivere particolari opzioni del metodo come gli authorizer, ad esempio se desideri utilizzare l’autenticazione Cognito per la tua operazione getDocumentation:

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

Terraform

Override dell’autorizzatore

Gli override degli authorizer per operazione non sono supportati con i moduli Terraform. L’intera API utilizza il metodo di autenticazione specificato durante la generazione dell’API (IAM, Cognito o Custom).

Per l’autorizzazione per operazione, dovresti implementare manualmente integrazioni esplicite come di seguito.

Integrazioni Esplicite

CDK

Se preferisci, puoi scegliere di non utilizzare le integrazioni predefinite e invece fornirne direttamente una per ogni operazione. Questo è utile se, ad esempio, ogni operazione deve utilizzare un tipo diverso di integrazione o desideri ricevere un errore di tipo quando aggiungi nuove operazioni:

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

Terraform

Per integrazioni esplicite per operazione con Terraform, dovresti modificare il modulo specifico dell’app generato per sostituire l’integrazione proxy predefinita con integrazioni specifiche per ogni operazione.

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

1. Rimuovi le route proxy predefinite (es. resource "aws_apigatewayv2_route" "proxy_routes")
2. Sostituisci la singola funzione Lambda con funzioni individuali per ogni operazione
3. Crea integrazioni e route specifiche per ogni operazione, riutilizzando lo stesso bundle ZIP:

HTTP API

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

# Rimuovi la singola funzione Lambda predefinita
 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 della configurazione
 }

# Rimuovi l'integrazione proxy predefinita
 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 della configurazione
 }

# Rimuovi le route proxy predefinite
 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 della configurazione
 }

# Aggiungi funzioni Lambda individuali per ogni operazione usando lo stesso 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 specifico per questa operazione
   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" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-GetDocumentation"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "getDocumentation.handler"  # Handler specifico per questa operazione
   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
 }

# Aggiungi integrazioni specifiche per ogni operazione
 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"
 }

# Aggiungi route specifiche per ogni operazione
 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"
 }

# Aggiungi permessi Lambda per ogni funzione
 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

# Rimuovi la singola funzione Lambda predefinita
 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 della configurazione
 }

# Rimuovi l'integrazione proxy predefinita
 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 della configurazione
 }

# Rimuovi le route proxy predefinite
 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 della configurazione
 }

# Aggiungi funzioni Lambda individuali per ogni operazione usando lo stesso 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 specifico per questa operazione
   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" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-GetDocumentation"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "getDocumentation.handler"  # Handler specifico per questa operazione
   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
 }

# Aggiungi risorse e metodi specifici per ogni operazione
 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"
 }

# Aggiorna il deployment per dipendere dalle nuove integrazioni
~ 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,
     ]))
   }
  }

# Aggiungi permessi Lambda per ogni funzione
 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}/*/*"
 }

Pattern di Integrazione

CDK

I costrutti API CDK generati supportano due pattern di integrazione:

• isolated crea una funzione Lambda per operazione. Questo è il pattern predefinito per le API generate.
• shared crea un singolo router Lambda predefinito e lo riutilizza per ogni operazione a meno che non si sovrascrivano integrazioni specifiche.

isolated offre permessi e configurazione più granulari per operazione. shared riduce la proliferazione di Lambda e integrazioni API Gateway pur consentendo override selettivi.

Ad esempio, impostando pattern su 'shared' si crea una singola funzione invece di una per integrazione:

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

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

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

Terraform

I moduli Terraform utilizzano automaticamente il router pattern - questo è l’approccio predefinito e unico supportato. Il modulo generato crea una singola funzione Lambda che gestisce tutte le operazioni API.

Puoi semplicemente istanziare il modulo predefinito per ottenere il router pattern:

# Router pattern predefinito - singola funzione Lambda per tutte le operazioni
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name

  # La singola funzione Lambda gestisce automaticamente tutte le operazioni
  tags = local.common_tags
}

Generazione del Codice

CDK

Poiché le operazioni in FastAPI sono definite in Python e l’infrastruttura CDK in TypeScript, strumentiamo la generazione del codice per fornire metadati al costrutto CDK e garantire un’interfaccia type-safe per le integrazioni.

Un target generate:<ApiName>-metadata viene aggiunto al project.json dei costrutti comuni per facilitare questa generazione, producendo un file come packages/common/constructs/src/generated/my-api/metadata.gen.ts. Essendo generato al momento della build, viene ignorato nel version control.

Compilare prima del deploy

Dovrai eseguire una build ogni volta che modifichi la tua API per garantire che i tipi consumati dal costrutto CDK siano aggiornati.

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Ricaricamento a caldo

Se stai lavorando attivamente sia sull’infrastruttura CDK che su FastAPI, puoi usare nx watch per rigenerare questi tipi ogni volta che apporti modifiche all’API:

pnpm

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

yarn

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

npm

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

bun

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

Terraform

Limitazioni di Terraform

Non supportiamo integrazioni type-safe per Terraform, quindi nessun target di generazione codice viene configurato se hai selezionato Terraform come iacProvider.

auth = iam

Concessione dell’Accesso (Solo IAM)

Se hai selezionato l’autenticazione IAM, puoi usare il metodo grantInvokeAccess per concedere l’accesso alla tua API:

CDK

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

Terraform

# Crea una policy IAM per consentire l'invocazione dell'API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "MyApiInvokePolicy"
  description = "Policy per consentire l'invocazione della FastAPI"

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

# Allega la policy a un ruolo IAM (es. per utenti autenticati)
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 allega a un ruolo esistente per nome
resource "aws_iam_role_policy_attachment" "api_invoke_access_existing" {
  role       = "MyExistingRole"
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

Gli output principali dal modulo API utilizzabili per le policy IAM sono:

• module.my_api.api_execution_arn - Per concedere permessi execute-api:Invoke
• module.my_api.api_arn - L’ARN di API Gateway
• module.my_api.lambda_function_arn - L’ARN della funzione Lambda

Sviluppo Locale

Il generatore configura un server di sviluppo locale che puoi eseguire 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

Questo avvia un server di sviluppo FastAPI locale con:

• Auto-reload alle modifiche del codice
• Documentazione API interattiva su /docs o /redoc
• Schema OpenAPI su /openapi.json

Invocare la tua FastAPI

Per invocare la tua API da un sito React, puoi utilizzare il generatore connection.

Connessioni

Usa il generatore connection per integrare questo progetto con altri nel tuo workspace. Le seguenti connessioni coinvolgono questo progetto:

React to FastAPI Chiama un'API Python FastAPI da un sito React

FastAPI to Python DynamoDB Collega un FastAPI a una tabella DynamoDB