FastAPI

FastAPI est un framework pour construire des APIs en Python.

Le générateur FastAPI crée une nouvelle application FastAPI avec une infrastructure AWS CDK ou Terraform. Le backend généré utilise AWS Lambda pour un déploiement serverless, exposé via une API AWS API Gateway. Il configure AWS Lambda Powertools pour l’observabilité, incluant la journalisation, le traçage AWS X-Ray et les métriques CloudWatch.

Utilisation

Générer une FastAPI

Vous pouvez générer une nouvelle application FastAPI de deux manières :

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - py#api
5. Remplissez les paramètres requis
   • framework: fastapi
6. Cliquez sur 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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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

Options

Paramètre	Type	Par défaut	Description
name Requis	string	-	Nom du projet API à générer
framework	fastapi	fastapi	Le framework d'API à utiliser.
integrationPattern	isolated | shared	isolated	Comment les intégrations API Gateway sont générées pour l'API. Choisissez entre isolated (par défaut) et shared.
auth	iam | cognito | custom	iam	La méthode utilisée pour s'authentifier auprès de votre API. Choisissez entre iam (par défaut), cognito ou custom.
directory	string	packages	Le répertoire dans lequel stocker l'application.
subDirectory	string	-	Le sous-répertoire dans lequel le projet est placé. Par défaut, il s'agit du nom du projet.
iac	inherit | cdk | terraform	inherit	Le fournisseur IaC préféré. Par défaut, celui-ci est hérité de votre sélection initiale.
moduleName	string	-	Nom du module Python
infra	rest-lambda | http-lambda | none	rest-lambda	Le type d'infrastructure à utiliser pour déployer cette API.
preferInstallDependencies	boolean	true	Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir sur false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Choix du type d’API

Vous pouvez choisir entre une REST API ou une HTTP API pour déployer votre API. Veuillez consulter le API Gateway Developer Guide pour vous aider à décider.

Type d’API

Sélectionnez rest-lambda (par défaut) comme infra si vous prévoyez de construire des opérations de streaming.

Pattern d’intégration

L’option integrationPattern est par défaut isolated, ce qui crée un Lambda par opération FastAPI. Sélectionnez shared si vous préférez un seul gestionnaire Lambda partagé pour toute l’API, avec des remplacements optionnels par opération.

Sortie du générateur

Le générateur va créer la structure de projet suivante dans le répertoire <directory>/<api-name> :

• project.json Configuration du projet et cibles de build
• pyproject.toml Configuration du projet Python et dépendances
• run.sh Script de bootstrap Lambda Web Adapter pour démarrer l’application FastAPI via uvicorn
• Répertoire<module_name>

  • __init__.py Initialisation du module
  • init.py Configure l’application FastAPI et le middleware powertools
  • main.py Implémentation de l’API
• Répertoirescripts

  • generate_open_api.py Script pour générer un schéma OpenAPI depuis l’app FastAPI

Infrastructure

Ce générateur fournit de l’infrastructure as code basée sur votre iacProvider choisi. Il créera un projet dans packages/common qui inclut les constructions CDK ou modules Terraform pertinents.

Le projet commun d’infrastructure as code est structuré comme suit :

CDK

• Répertoirepackages/common/constructs

  • Répertoiresrc

    • Répertoireapp/ Constructions pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Constructions génériques réutilisées par celles dans app

      • …
    • index.ts Point d’entrée exportant les constructions depuis app
  • project.json Cibles de build et configuration du projet

Projet généré

Ce projet est généré avec le générateur ts#project et configure donc les mêmes cibles de build.

Terraform

• Répertoirepackages/common/terraform

  • Répertoiresrc

    • Répertoireapp/ Modules Terraform pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Modules génériques réutilisés par ceux dans app

      • …
  • project.json Cibles de build et configuration du projet

Projet généré

Ce projet est généré avec le générateur terraform#project et configure donc les mêmes cibles de build.

Pour déployer votre API, les fichiers suivants sont générés :

CDK

• Répertoirepackages/common/constructs/src

  • Répertoireapp

    • Répertoireapis

      • <project-name>.ts Construct CDK pour déployer votre API
  • Répertoirecore

    • Répertoireapi

      • http-api.ts Construct CDK pour déployer une API HTTP (si vous avez choisi de déployer une API HTTP)
      • rest-api.ts Construct CDK pour déployer une API REST (si vous avez choisi de déployer une API REST)
      • utils.ts Utilitaires pour les constructs d’API

Terraform

• Répertoirepackages/common/terraform/src

  • Répertoireapp

    • Répertoireapis

      • Répertoire<project-name>

        • <project-name>.tf Module pour déployer votre API
  • Répertoirecore

    • Répertoireapi

      • Répertoirehttp-api

        • http-api.tf Module pour déployer une API HTTP (si vous avez choisi de déployer une API HTTP)
      • Répertoirerest-api

        • rest-api.tf Module pour déployer une API REST (si vous avez choisi de déployer une API REST)

Architecture

L’application déployée a l’architecture suivante :

REST API

Les API REST incluent une Web ACL AWS WAFv2 devant l’étape API Gateway avec l’ensemble de règles par défaut géré par AWS activé.

HTTP API

Les API HTTP ne prennent pas en charge WAF directement — si vous avez besoin de la protection WAF, choisissez REST API à la place ou placez l’API HTTP derrière une distribution CloudFront.

Implémentation de votre FastAPI

L’implémentation principale de l’API se trouve dans main.py. C’est ici que vous définissez vos routes API et leurs implémentations. Voici un exemple :

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

Le générateur configure automatiquement plusieurs fonctionnalités :

1. Intégration d’AWS Lambda Powertools pour l’observabilité
2. Middleware de gestion des erreurs
3. Corrélation des requêtes/réponses
4. Collecte de métriques
5. Déploiement AWS Lambda via Lambda Web Adapter avec uvicorn
6. Streaming typé (API REST uniquement)

Observabilité avec AWS Lambda Powertools

Journalisation

Le générateur configure la journalisation structurée avec AWS Lambda Powertools. Vous pouvez accéder au logger dans vos gestionnaires de route :

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}

Le logger inclut automatiquement :

• Des IDs de corrélation pour le traçage des requêtes
• Le chemin et la méthode de la requête
• Les informations de contexte Lambda
• Des indicateurs de démarrage à froid

Traçage

Le traçage AWS X-Ray est configuré automatiquement. Vous pouvez ajouter des sous-segments personnalisés à vos traces :

from .init import app, tracer

@app.get("/items/{item_id}")
@tracer.capture_method
def read_item(item_id: int):
    # Crée un nouveau sous-segment
    with tracer.provider.in_subsegment("fetch-item-details"):
        # Votre logique ici
        return {"item_id": item_id}

Métriques

Des métriques CloudWatch sont collectées automatiquement pour chaque requête. Vous pouvez ajouter des métriques personnalisées :

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}

Les métriques par défaut incluent :

• Le nombre de requêtes
• Les compteurs de succès/échec
• Les métriques de démarrage à froid
• Des métriques par route

Gestion des erreurs

Le générateur inclut une gestion d’erreurs complète :

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}

Les exceptions non gérées sont capturées par le middleware et :

1. Journalisent l’exception complète avec la stack trace
2. Enregistrent une métrique d’échec
3. Renvoient une réponse 500 sécurisée au client
4. Préservent l’ID de corrélation

Modèles de réponse

Il est recommandé de spécifier des modèles de réponse pour vos opérations API afin de faciliter la génération de code si vous utilisez le générateur connection. Voir ici pour plus de détails.

Accès à l’utilisateur appelant

Lorsque votre API est protégée par authentification, vos gestionnaires de route ont souvent besoin de savoir qui appelle. La FastAPI générée s’exécute dans AWS Lambda via le Lambda Web Adapter, qui transmet le contexte de requête API Gateway sous forme de JSON dans l’en-tête x-amzn-request-context. Vous pouvez le lire depuis la Request FastAPI pour extraire l’identité de l’appelant.

À titre d’exemple, ajoutons un endpoint /me qui retourne les détails de l’utilisateur appelant. Nous implémenterons l’extraction comme une dépendance FastAPI afin qu’elle puisse être réutilisée entre les routes. La forme du contexte de requête — et donc la façon dont vous extrayez l’identité — dépend à la fois de votre méthode auth sélectionnée et du fait que vous ayez déployé une API REST ou HTTP.

auth = iam

Pour l’authentification IAM, nous recherchons l’appelant dans Cognito en utilisant le sub extrait du contexte de requête API Gateway. Créez identity.py à côté de 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:
    # Le Lambda Web Adapter transmet le contexte de requête API Gateway sous forme de 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(
        # Suppose que l'ID du user pool est configuré dans l'environnement 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:
    # Le Lambda Web Adapter transmet le contexte de requête API Gateway sous forme de 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(
        # Suppose que l'ID du user pool est configuré dans l'environnement 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

Avec auth: 'cognito', l’autorisateur Cognito User Pools d’API Gateway vérifie le JWT que l’appelant fournit dans l’en-tête Authorization et place les claims vérifiés sur le contexte de requête.

Créez identity.py à côté de 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:
    # Le Lambda Web Adapter transmet le contexte de requête API Gateway sous forme de 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

Les API HTTP utilisent un autorisateur JWT qui place les claims vérifiés sous 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:
    # Le Lambda Web Adapter transmet le contexte de requête API Gateway sous forme de 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)]

Aucune vérification de token requise

Vous n’avez pas besoin de bibliothèque de vérification JWT ici — l’autorisateur Cognito User Pools d’API Gateway a déjà vérifié la signature, l’émetteur, les scopes et l’expiration au moment où votre Lambda s’exécute. Si l’une de ces vérifications échoue, API Gateway retourne 401 Unauthorized et votre gestionnaire n’est jamais invoqué.

Vous pouvez ensuite injecter la dépendance CurrentUser dans n’importe quelle route qui a besoin de l’identité de l’appelant :

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 générée supporte les réponses streamées nativement lors de l’utilisation d’une API REST. L’infrastructure est configurée pour utiliser le AWS Lambda Web Adapter afin d’exécuter votre FastAPI via uvicorn dans Lambda, avec ResponseTransferMode.STREAM dans API Gateway pour toutes les opérations d’API REST, ce qui permet au streaming de fonctionner aux côtés des opérations non-streamées.

Utilisation de JsonStreamingResponse

Le fichier init.py généré exporte une classe JsonStreamingResponse qui fournit un streaming typé avec une génération de schéma OpenAPI appropriée. Cela garantit que le générateur connection peut produire des méthodes client de streaming correctement typées.

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. Sérialise les modèles Pydantic au format JSON Lines (application/jsonl)
2. Fournit un helper openapi_response qui génère le schéma OpenAPI correct avec itemSchema, permettant au générateur connection de produire des méthodes client de streaming typées

Consommation

Pour consommer un flux de réponses, vous pouvez utiliser le générateur connection qui fournira une méthode typée pour itérer sur vos chunks streamés.

Déploiement de votre FastAPI

Le générateur FastAPI crée une infrastructure CDK ou Terraform en fonction du iacProvider sélectionné. Vous pouvez l’utiliser pour déployer votre FastAPI.

CDK

Le construct CDK pour déployer votre API se trouve dans le dossier common/constructs. Vous pouvez l’utiliser dans une application CDK :

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

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

Ceci configure :

1. Une fonction AWS Lambda pour chaque opération de l’application FastAPI
2. Une API Gateway HTTP/REST comme déclencheur
3. Les rôles et permissions IAM
4. Un groupe de logs CloudWatch
5. La configuration de traçage X-Ray
6. Un espace de noms pour les métriques CloudWatch

Configuration CORS CDK

Si votre solution inclut un site web, vous pouvez configurer sa distribution CloudFront comme seule origine CORS autorisée dans les intégrations API gateway / API AWS Lambda pour les API HTTP / REST. Vous pouvez appeler la méthode restrictCorsTo de l’API avec des constructs de site web, des distributions CloudFront, des chaînes d’origine, ou un mélange de ceux-ci.

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

Le construct MyWebsite peut être généré en utilisant le générateur ts#website

auth = cognito

Authentification Cognito

Si vous avez choisi l’authentification Cognito, vous devrez fournir la propriété identity au construct 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,
    });
  }
}

Le construct UserIdentity peut être généré avec le générateur 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

Les modules Terraform pour déployer votre API se trouvent dans le dossier common/terraform. Vous pouvez les utiliser dans une configuration Terraform.

Le module API stocke son zip de déploiement Lambda dans un bucket S3 d’assets partagé — voir le guide d’infrastructure Terraform pour plus de détails. Instanciez le module core/asset-bucket une fois par déploiement et passez sa sortie bucket_name à chaque module API / Lambda via l’entrée 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

  # Variables d'environnement pour la fonction Lambda
  env = {
    ENVIRONMENT = var.environment
    LOG_LEVEL   = "INFO"
  }

  # Politiques IAM supplémentaires si nécessaire
  additional_iam_policy_statements = [
    # Ajoutez les permissions supplémentaires nécessaires
  ]

  tags = local.common_tags
}

Ceci configure :

1. Une fonction AWS Lambda qui sert toutes les routes FastAPI
2. Une API Gateway HTTP/REST comme déclencheur
3. Les rôles et permissions IAM
4. Un groupe de logs CloudWatch
5. La configuration de traçage X-Ray
6. La configuration CORS

Configuration CORS Terraform

Si votre solution inclut un module de site web Terraform, vous pouvez utiliser son nom de domaine CloudFront pour restreindre CORS. Étant donné un nom de domaine CloudFront <domain_name>, dans le module Terraform pour déployer votre API, ajoutez

• une propriété cors_allow_origins, définie sur ["http://localhost:4200", "http://localhost:4300", "https://<domain name>"], pour les API HTTP. Cela restreint le CORS de la passerelle API à cette distribution et à l’hôte local.
• une variable d’environnement ALLOWED_ORIGINS, définie sur "https://<domain_name>", pour les API REST. Cela définit la distribution CloudFront comme la seule origine CORS autorisée (autre que l’hôte local) dans les intégrations AWS Lambda. Notez que cette restriction ne s’applique pas aux OPTIONS de pré-vérification - veuillez +1 ce problème GitHub pour aider à prioriser la résolution de ce point.

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

Le construct MyWebsite peut être généré en utilisant le générateur ts#website

auth = cognito

Authentification Cognito

Si vous avez choisi l’authentification Cognito, vous devrez fournir la configuration 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
}

Vous pouvez configurer le User Pool et Client Cognito en utilisant les ressources ou modules Terraform appropriés.

Le module Terraform fournit plusieurs sorties utilisables :

# Accès à l'endpoint de l'API
output "api_url" {
  value = module.my_api.stage_invoke_url
}

# Accès aux détails de la fonction Lambda
output "lambda_function_name" {
  value = module.my_api.lambda_function_name
}

# Accès au rôle IAM pour des permissions supplémentaires
output "lambda_execution_role_arn" {
  value = module.my_api.lambda_execution_role_arn
}

Vous pouvez personnaliser les paramètres CORS en passant des variables au module :

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

  asset_bucket_name = module.asset_bucket.bucket_name

  # Configuration CORS personnalisée
  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

Pour les API REST, le construct généré associe par défaut une Web ACL AWS WAFv2 à l’étape API Gateway. La Web ACL utilise l’ensemble de règles par défaut géré par AWS (AWSManagedRulesCommonRuleSet et AWSManagedRulesKnownBadInputsRuleSet), offrant une protection contre les exploits web courants, y compris le Top 10 OWASP. Les journaux de requêtes WAF sont écrits dans un groupe CloudWatch Logs.

Déviation de SizeRestrictions_BODY par rapport aux valeurs par défaut

La règle SizeRestrictions_BODY de AWSManagedRulesCommonRuleSet est remplacée par Count plutôt que Block, car la limite de 8 Ko de la règle est trop restrictive pour la plupart des API. Les requêtes surdimensionnées seront toujours enregistrées en tant que métriques afin que vous puissiez les surveiller. Consultez le guide AWS WAF body size limits pour plus de détails. API Gateway applique nativement sa taille de charge utile maximale de 10 Mo, renvoyant un 413 pour les requêtes plus volumineuses.

Vous pouvez modifier le construct rest-api généré pour ajouter, supprimer ou ajuster des règles (par exemple, pour ajouter des règles basées sur le taux ou des groupes de règles gérées supplémentaires).

CDK

Pour désactiver cette fonctionnalité (par exemple, pour attacher votre propre Web ACL), définissez enableWaf sur false :

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

Terraform

Pour désactiver cette fonctionnalité (par exemple, pour attacher votre propre Web ACL), définissez enable_waf sur 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

Journalisation des accès

Pour les API REST, l’infrastructure générée active la journalisation des accès par défaut, écrivant une ligne JSON structurée par requête dans un groupe CloudWatch Logs dédié. Le groupe de journaux est chiffré avec une clé KMS gérée par le client et conservé pendant un an.

API Gateway écrit les journaux d’accès en utilisant un rôle CloudWatch Logs au niveau du compte. Ce rôle est configuré sur le paramètre AWS::ApiGateway::Account, qui est un singleton par région par compte — il n’y a qu’un seul rôle pour chaque API REST dans la région. Pour gérer cela en toute sécurité à travers plusieurs stacks déployées indépendamment, l’infrastructure générée :

• Crée un rôle CloudWatch Logs partagé et le configure sur le compte uniquement lorsqu’aucun rôle fonctionnel n’est déjà défini, de sorte que les déploiements n’écrasent jamais un rôle appartenant à une autre stack.
• Laisse le paramètre du compte intact lors du démontage, de sorte que la destruction d’une stack ne désactive jamais la journalisation pour les autres API REST dans la région.

CDK

Le rôle du compte est géré par le construct ApiGatewayAccount, un singleton à portée de stack résolu via ApiGatewayAccount.ensure(scope). Chaque stage d’API REST en dépend, et le rôle est configuré par une ressource personnalisée basée sur Lambda.

Vous pouvez personnaliser le format du journal d’accès en passant deployOptions lors de la construction de votre API :

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

Terraform

Le rôle du compte est géré par le module core/api/api-gateway-account, qui est instancié par le module API généré. Il configure le compte de manière idempotente et n’est jamais réinitialisé lors d’un terraform destroy.

Vous pouvez personnaliser le format du journal d’accès en modifiant le bloc access_log_settings sur la ressource aws_api_gateway_stage dans le module API généré.

Intégrations

Les constructs CDK pour l’API REST/HTTP sont configurés pour fournir une interface typée permettant de définir des intégrations pour chacune de vos opérations.

CDK

Les constructs CDK offrent un support complet d’intégration typée comme décrit ci-dessous.

Terraform

Pattern de routeur

Les modules Terraform utilisent le “modèle router” avec une seule fonction Lambda servant toutes les opérations. Les intégrations typées ne sont pas supportées - le module crée une fonction Lambda unique qui gère toutes les requêtes API.

Pour des intégrations explicites par opération avec Terraform, vous devrez créer manuellement des fonctions Lambda individuelles et des routes API Gateway. Voir la section Intégrations explicites pour des exemples.

Intégrations par défaut

CDK

Vous pouvez utiliser la méthode statique defaultIntegrations pour utiliser le modèle par défaut, qui définit une fonction AWS Lambda individuelle pour chaque opération :

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

Terraform

Les modules Terraform utilisent automatiquement le modèle router avec une seule fonction Lambda. Aucune configuration supplémentaire n’est nécessaire :

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

  asset_bucket_name = module.asset_bucket.bucket_name

  # Le module crée automatiquement une fonction Lambda unique
  # qui gère toutes les opérations de l'API
  tags = local.common_tags
}

Accès aux intégrations

CDK

Vous pouvez accéder aux fonctions AWS Lambda sous-jacentes via la propriété integrations du construct API, de manière typée. Par exemple, si votre API définit une opération nommée sayHello et que vous devez ajouter des permissions à cette fonction, vous pouvez le faire comme suit :

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

// sayHello est typé selon les opérations définies dans votre API
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
  effect: Effect.ALLOW,
  actions: [...],
  resources: [...],
}));

Si votre API utilise le modèle shared, la fonction Lambda router partagée est exposée via api.integrations.$router :

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

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

Terraform

Avec le modèle router de Terraform, il n’y a qu’une seule fonction Lambda. Vous pouvez y accéder via les sorties du module :

# Accorder des permissions supplémentaires à la fonction Lambda unique
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/*"
      }
    ]
  })
}

Personnalisation des options par défaut

CDK

Si vous souhaitez personnaliser les options utilisées lors de la création des fonctions Lambda pour chaque intégration par défaut, vous pouvez utiliser la méthode withDefaultOptions. Par exemple, si vous voulez que toutes vos fonctions Lambda résident dans un VPC :

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

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

Terraform

Pour personnaliser des options comme la configuration VPC, vous devez modifier le module Terraform généré. Par exemple, pour ajouter le support VPC à toutes les fonctions Lambda :

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

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

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

# Mettre à jour la ressource Lambda
resource "aws_lambda_function" "api_lambda" {
  # ... configuration existante ...

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

Puis utiliser le module avec la configuration VPC :

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

  asset_bucket_name = module.asset_bucket.bucket_name

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

Personnalisation des options par opération

CDK

Pour personnaliser les options utilisées pour créer l’intégration par défaut pour des opérations spécifiques (sans affecter les autres), vous pouvez utiliser la méthode withOperationOptions. Par exemple, si vous souhaitez augmenter le timeout de la fonction Lambda pour une seule opération :

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

// Les opérations sélectionnées restent des intégrations par défaut, elles sont donc toujours typées en conséquence :
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({ ... }));

Les options que vous spécifiez sont fusionnées avec les options d’intégration par défaut (et toutes les options définies via withDefaultOptions). Notez que vous ne pouvez pas spécifier d’options pour les opérations que vous avez remplacées via withOverrides, car celles-ci n’utilisent plus l’intégration par défaut.

Vous rencontrerez une erreur de type si la même opération est ciblée à la fois par withOperationOptions et withOverrides, quel que soit l’ordre dans lequel vous les appelez.

Terraform

Pour personnaliser les options pour des opérations spécifiques avec Terraform, vous devez modifier le module Terraform généré pour configurer des fonctions Lambda individuelles par opération (voir la section Intégrations explicites ci-dessous).

Surcharge des intégrations

CDK

Vous pouvez aussi surcharger les intégrations pour des opérations spécifiques en utilisant la méthode withOverrides. Chaque surcharge doit spécifier une propriété integration typée selon le construct CDK d’intégration approprié pour l’API HTTP ou REST. La méthode withOverrides est également typée. Par exemple, si vous voulez rediriger une API getDocumentation vers une documentation hébergée sur un site externe :

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

Vous remarquerez que l’intégration surchargée n’a plus de propriété handler lorsqu’on y accède via api.integrations.getDocumentation.

Vous pouvez ajouter des propriétés supplémentaires à une intégration qui seront également typées, permettant d’abstraire d’autres types d’intégration tout en conservant le typage. Par exemple, si vous avez créé une intégration S3 pour une API REST et que vous souhaitez référencer le bucket pour une opération particulière :

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

// Plus tard, peut-être dans un autre fichier, vous pouvez accéder à la propriété bucket
// que nous avons définie de manière typée
api.integrations.getFile.bucket.grantRead(...);

Terraform

Surcharges d’intégration

La surcharge d’intégrations spécifiques n’est pas supportée avec les modules Terraform car ils utilisent le modèle router. Toutes les opérations sont gérées par la fonction Lambda unique.

Pour des types d’intégration différents par opération, vous devrez implémenter manuellement des intégrations explicites (voir la section Intégrations explicites ci-dessous).

Surcharge des autorisations

CDK

Vous pouvez aussi fournir des options dans votre intégration pour surcharger des options de méthode spécifiques comme les autorisations. Par exemple, si vous souhaitez utiliser l’authentification Cognito pour votre opération getDocumentation :

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

Terraform

Surcharges d’autorisateur

Les surcharges d’autorisations par opération ne sont pas supportées avec les modules Terraform. L’API entière utilise la méthode d’authentification spécifiée lors de la génération de l’API (IAM, Cognito, ou Custom).

Pour une autorisation par opération, vous devrez implémenter manuellement des intégrations explicites comme ci-dessous.

Intégrations explicites

CDK

Si vous préférez, vous pouvez choisir de ne pas utiliser les intégrations par défaut et fournir directement une intégration pour chaque opération. Ceci est utile si, par exemple, chaque opération nécessite un type d’intégration différent ou si vous voulez obtenir une erreur de type lors de l’ajout de nouvelles opérations :

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

Terraform

Pour des intégrations explicites par opération avec Terraform, vous devez modifier le module généré spécifique à l’application pour remplacer l’intégration proxy par défaut par des intégrations spécifiques à chaque opération.

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

1. Supprimer les routes proxy par défaut (ex: resource "aws_apigatewayv2_route" "proxy_routes")
2. Remplacer la fonction Lambda unique par des fonctions individuelles pour chaque opération
3. Créer des intégrations et routes spécifiques pour chaque opération, en réutilisant le même bundle ZIP :

HTTP API

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

# Supprimer la fonction Lambda unique par défaut
 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
   # ... reste de la configuration
 }

# Supprimer l'intégration proxy par défaut
 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
   # ... reste de la configuration
 }

# Supprimer les routes proxy par défaut
 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}"
   # ... reste de la configuration
 }

# Ajouter des fonctions Lambda individuelles pour chaque opération en utilisant le même 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 spécifique pour cette opération
   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 spécifique pour cette opération
   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
 }

# Ajouter des intégrations spécifiques pour chaque opération
 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"
 }

# Ajouter des routes spécifiques pour chaque opération
 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"
 }

# Ajouter des permissions Lambda pour chaque fonction
 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

# Supprimer la fonction Lambda unique par défaut
 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
   # ... reste de la configuration
 }

# Supprimer l'intégration proxy par défaut
 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
   # ... reste de la configuration
 }

# Supprimer les routes proxy par défaut
 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}"
   # ... reste de la configuration
 }

# Ajouter des fonctions Lambda individuelles pour chaque opération en utilisant le même 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 spécifique pour cette opération
   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 spécifique pour cette opération
   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
 }

# Ajouter des ressources et méthodes spécifiques pour chaque opération
 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"
 }

# Mettre à jour le déploiement pour dépendre des nouvelles intégrations
~ 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,
     ]))
   }
  }

# Ajouter des permissions Lambda pour chaque fonction
 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}/*/*"
 }

Modèle d’intégration

CDK

Les constructs d’API CDK générés supportent deux modèles d’intégration :

• isolated crée une fonction Lambda par opération. C’est le modèle par défaut pour les API générées.
• shared crée une seule fonction Lambda router par défaut et la réutilise pour chaque opération sauf si vous surchargez des intégrations spécifiques.

isolated vous donne des permissions et une configuration plus granulaires par opération. shared réduit la prolifération des fonctions Lambda et des intégrations API Gateway tout en permettant des surcharges sélectives.

Par exemple, définir pattern sur 'shared' crée une fonction unique au lieu d’une par intégration :

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

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

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

Terraform

Les modules Terraform utilisent automatiquement le modèle router - c’est l’approche par défaut et la seule supportée. Le module généré crée une fonction Lambda unique qui gère toutes les opérations de l’API.

Vous pouvez simplement instancier le module par défaut pour obtenir le modèle router :

# Modèle router par défaut - fonction Lambda unique pour toutes les opérations
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name

  # La fonction Lambda unique gère automatiquement toutes les opérations
  tags = local.common_tags
}

Génération de code

CDK

Puisque les opérations FastAPI sont définies en Python et l’infrastructure CDK en TypeScript, nous instrumentons la génération de code pour fournir des métadonnées au construct CDK afin d’offrir une interface typée pour les intégrations.

Une cible generate:<ApiName>-metadata est ajoutée au project.json des constructs communs pour faciliter cette génération, produisant un fichier comme packages/common/constructs/src/generated/my-api/metadata.gen.ts. Ce fichier étant généré au build, il est ignoré dans le contrôle de version.

Compiler avant de déployer

Vous devrez exécuter un build après chaque modification de votre API pour maintenir les types consommés par le construct CDK à jour.

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Rechargement à chaud

Si vous travaillez simultanément sur l’infrastructure CDK et FastAPI, vous pouvez utiliser nx watch pour régénérer ces types à chaque modification :

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

Limitations de Terraform

Nous ne supportons pas les intégrations typées pour Terraform, donc aucune cible de génération de code n’est configurée si vous avez choisi Terraform comme iacProvider.

auth = iam

Octroi d’accès (IAM uniquement)

Si vous avez choisi l’authentification IAM, vous pouvez utiliser la méthode grantInvokeAccess pour octroyer l’accès à votre API :

CDK

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

Terraform

# Crée une politique IAM pour autoriser l'invocation de l'API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "MyApiInvokePolicy"
  description = "Politique pour autoriser l'invocation de FastAPI"

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

# Attache la politique à un rôle IAM (ex: utilisateurs authentifiés)
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
}

# Ou attache à un rôle existant par nom
resource "aws_iam_role_policy_attachment" "api_invoke_access_existing" {
  role       = "MyExistingRole"
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

Les sorties clés du module API utilisables pour les politiques IAM sont :

• module.my_api.api_execution_arn - Pour autoriser execute-api:Invoke
• module.my_api.api_arn - L’ARN de l’API Gateway
• module.my_api.lambda_function_arn - L’ARN de la fonction Lambda

Développement local

Le générateur configure un serveur de développement local que vous pouvez exécuter avec :

pnpm

pnpm nx serve my-api

yarn

yarn nx serve my-api

npm

npx nx serve my-api

bun

bunx nx serve my-api

Ceci démarre un serveur de développement FastAPI local avec :

• Rechargement automatique sur modification
• Documentation interactive de l’API sur /docs ou /redoc
• Schéma OpenAPI sur /openapi.json

Invocation de votre FastAPI

Pour invoquer votre API depuis un site React, vous pouvez utiliser le générateur connection.

Connexions

Utilisez le générateur connection pour intégrer ce projet avec d’autres dans votre espace de travail. Les connexions suivantes impliquent ce projet :

React vers FastAPI Appeler une API Python FastAPI depuis un site React

FastAPI vers Python DynamoDB Connecter une FastAPI à une table DynamoDB