Smithy TypeScript API

Smithy es un lenguaje de definición de interfaces independiente del protocolo para crear APIs de manera modelada.

El generador de API TypeScript para Smithy crea una nueva API usando Smithy para la definición del servicio y el SDK de servidor TypeScript para Smithy para la implementación. El generador provee infraestructura como código con CDK o Terraform para desplegar tu servicio en AWS Lambda, expuesto a través de una API REST de AWS API Gateway. Ofrece desarrollo de APIs con seguridad de tipos mediante generación automática de código a partir de modelos Smithy. El manejador generado utiliza AWS Lambda Powertools para TypeScript para observabilidad, incluyendo registro, trazado con AWS X-Ray y métricas de CloudWatch.

Uso

Generar una API TypeScript con Smithy

Puedes generar una nueva API TypeScript con Smithy de dos formas:

VSCode
CLI

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

pnpm nx g @aws/nx-plugin:ts#api --framework=smithy

yarn nx g @aws/nx-plugin:ts#api --framework=smithy

npx nx g @aws/nx-plugin:ts#api --framework=smithy

bunx nx g @aws/nx-plugin:ts#api --framework=smithy

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

pnpm nx g @aws/nx-plugin:ts#api --framework=smithy --dry-run

yarn nx g @aws/nx-plugin:ts#api --framework=smithy --dry-run

npx nx g @aws/nx-plugin:ts#api --framework=smithy --dry-run

bunx nx g @aws/nx-plugin:ts#api --framework=smithy --dry-run

Opciones

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

Salida del Generador

El generador crea dos proyectos relacionados en el directorio <directory>/<api-name>:

Directoriomodel/ Proyecto del modelo Smithy
- project.json Configuración del proyecto y objetivos de build
- smithy-build.json Configuración de build para Smithy
- build.Dockerfile Configuración de Docker para construir artefactos Smithy
- Directoriosrc/
  - main.smithy Definición principal del servicio
  - Directoriooperations/
    echo.smithy Definición de operación de ejemplo
Directoriobackend/ Implementación del backend en TypeScript
- project.json Configuración del proyecto y objetivos de build
- rolldown.config.ts Configuración de bundling
- Directoriosrc/
  - handler.ts Manejador de AWS Lambda
  - local-server.ts Servidor local para desarrollo
  - service.ts Implementación del servicio
  - context.ts Definición del contexto del servicio
  - Directoriooperations/
    echo.ts Implementación de operación de ejemplo
  - Directoriogenerated/ SDK TypeScript generado (creado durante el build)
    …

Infraestructura

Dado que este generador crea infraestructura como código según el iacProvider seleccionado, generará un proyecto en packages/common que incluye los constructos CDK o módulos Terraform relevantes.

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

CDK
Terraform

Directoriopackages/common/constructs
- Directoriosrc
  - Directorioapp/ Constructos para infraestructura específica de un proyecto/generador
    Directorioapis/
    <project-name>.ts Constructo CDK para desplegar tu API
  - Directoriocore/ Constructos genéricos reutilizables por los de app
    Directorioapi/
    rest-api.ts Constructo CDK para desplegar una API REST
    utils.ts Utilidades para los constructos de API
  - index.ts Punto de entrada que exporta los constructos de app
- project.json Objetivos de build y configuración del proyecto

Directoriopackages/common/terraform
- Directoriosrc
  - Directorioapp/ Módulos Terraform para infraestructura específica de un proyecto/generador
    Directorioapis/
    Directorio<project-name>/
    <project-name>.tf Módulo para desplegar tu API
  - Directoriocore/ Módulos genéricos reutilizados por los de app
    Directorioapi/
    Directoriorest-api/
    rest-api.tf Módulo para desplegar una API REST
- project.json Objetivos de build y configuración del proyecto

Arquitectura

La API Smithy desplegada tiene la siguiente arquitectura, con un Web ACL de AWS WAFv2 frente al stage de API Gateway:

Implementando tu API Smithy

Definiendo Operaciones en Smithy

Las operaciones se definen en archivos Smithy dentro del proyecto del modelo. La definición principal del servicio está en main.smithy:

$version: "2.0"

namespace your.namespace

use aws.protocols#restJson1
use smithy.framework#ValidationException

@title("YourService")
@restJson1
service YourService {
    version: "1.0.0"
    operations: [
        Echo,
        // Add your operations here
    ]
    errors: [
        ValidationException
    ]
}

Las operaciones individuales se definen en archivos separados en el directorio operations/:

$version: "2.0"

namespace your.namespace

@http(method: "POST", uri: "/echo")
operation Echo {
    input: EchoInput
    output: EchoOutput
}

structure EchoInput {
    @required
    message: String

    foo: Integer
    bar: String
}

structure EchoOutput {
    @required
    message: String
}

Implementando Operaciones en TypeScript

Las implementaciones de operaciones se encuentran en el directorio src/operations/ del proyecto backend. Cada operación se implementa usando los tipos generados del SDK de servidor TypeScript (generados en tiempo de build a partir de tu modelo Smithy).

import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';

export const Echo: EchoOperation<ServiceContext> = async (input) => {
  // Your business logic here
  return {
    message: `Echo: ${input.message}` // type-safe based on your Smithy model
  };
};

Las operaciones deben registrarse en la definición del servicio en src/service.ts:

import { ServiceContext } from './context.js';
import { YourServiceService } from './generated/ssdk/index.js';
import { Echo } from './operations/echo.js';
// Import other operations here

// Register operations to the service here
export const Service: YourServiceService<ServiceContext> = {
  Echo,
  // Add other operations here
};

Contexto del Servicio

Puedes definir un contexto compartido para tus operaciones en context.ts:

export interface ServiceContext {
  // Powertools tracer, logger and metrics are provided by default
  tracer: Tracer;
  logger: Logger;
  metrics: Metrics;
  // Add shared dependencies, database connections, etc.
  dbClient: any;
  userIdentity: string;
}

Este contexto se pasa a todas las implementaciones de operaciones y puede usarse para compartir recursos como conexiones a bases de datos, configuración o utilidades de registro.

Observabilidad con AWS Lambda Powertools

Registros

El generador configura registro estructurado usando AWS Lambda Powertools con inyección automática de contexto mediante middleware Middy.

export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
  .use(captureLambdaHandler(tracer))
  .use(injectLambdaContext(logger))
  .use(logMetrics(metrics))
  .handler(lambdaHandler);

Puedes acceder al logger desde tus implementaciones de operaciones vía el contexto:

import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';

export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
  ctx.logger.info('Your log message');
  // ...
};

Trazado

El trazado con AWS X-Ray se configura automáticamente mediante el middleware captureLambdaHandler.

export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
  .use(captureLambdaHandler(tracer))
  .use(injectLambdaContext(logger))
  .use(logMetrics(metrics))
  .handler(lambdaHandler);

Puedes añadir subsegmentos personalizados a tus trazas en tus operaciones:

import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';

export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
  // Creates a new subsegment
  const subsegment = ctx.tracer.getSegment()?.addNewSubsegment('custom-operation');
  try {
    // Your logic here
  } catch (error) {
    subsegment?.addError(error as Error);
    throw error;
  } finally {
    subsegment?.close();
  }
};

Métricas

Las métricas de CloudWatch se recopilan automáticamente para cada solicitud mediante el middleware logMetrics.

export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
  .use(captureLambdaHandler(tracer))
  .use(injectLambdaContext(logger))
  .use(logMetrics(metrics))
  .handler(lambdaHandler);

Puedes añadir métricas personalizadas en tus operaciones:

import { MetricUnit } from '@aws-lambda-powertools/metrics';
import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';

export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
  ctx.metrics.addMetric("CustomMetric", MetricUnit.Count, 1);
  // ...
};

Manejo de Errores

Smithy provee manejo de errores integrado. Puedes definir errores personalizados en tu modelo Smithy:

@error("client")
@httpError(400)
structure InvalidRequestError {
    @required
    message: String
}

Y registrarlos en tu operación/servicio:

operation MyOperation {
  ...
  errors: [InvalidRequestError]
}

Luego lanzarlos en tu implementación TypeScript:

import { InvalidRequestError } from '../generated/ssdk/index.js';

export const MyOperation: MyOperationHandler<ServiceContext> = async (input) => {
  if (!input.requiredField) {
    throw new InvalidRequestError({
      message: "Required field is missing"
    });
  }

  return { /* success response */ };
};

Acceso al Usuario que Realiza la Llamada

Cuando tu API está protegida por autenticación, tus operaciones a menudo necesitan saber quién está realizando la llamada. El enfoque recomendado es resolver la identidad del llamante una vez en el handler y pasarla a través del contexto del servicio para su consumo por operaciones específicas.

Modelaremos el caso no autorizado como un error de Smithy para que se serialice a una respuesta 403 adecuada. Agrégalo a tu modelo, por ejemplo en model/src/operations/errors.smithy, y referéncialo en cualquier operación que requiera identidad:

$version: "2.0"

namespace your.namespace

/// Thrown when the calling user cannot be determined
@error("client")
@httpError(403)
structure UnauthorizedError {
    @required
    message: String
}

Primero, expón la identidad resuelta en el contexto del servicio en src/context.ts. La proporcionamos como una función para que el UnauthorizedError se lance desde dentro de una operación (donde el Server SDK lo serializa a un 403), en lugar de desde el handler:

import { Logger } from '@aws-lambda-powertools/logger';
import { Metrics } from '@aws-lambda-powertools/metrics';
import { Tracer } from '@aws-lambda-powertools/tracer';

export interface Identity {
  sub: string;
  username: string;
}

/**
 * Context provided to all operations.
 */
export interface ServiceContext {
  tracer: Tracer;
  logger: Logger;
  metrics: Metrics;
  getIdentity: () => Promise<Identity>;
}

A continuación, escribe el resolver en src/identity.ts. Lanza UnauthorizedError cuando no se puede determinar el llamante. La implementación depende del método auth seleccionado:

Para la autenticación IAM, buscamos el llamante en Cognito usando el sub extraído del evento de API Gateway:

import { CognitoIdentityProvider } from '@aws-sdk/client-cognito-identity-provider';
import type { APIGatewayProxyEvent } from 'aws-lambda';
import { Identity } from './context.js';
import { UnauthorizedError } from './generated/ssdk/index.js';

const cognito = new CognitoIdentityProvider();

export const getIdentity = async (
  event: APIGatewayProxyEvent,
): Promise<Identity> => {
  const cognitoAuthenticationProvider =
    event.requestContext?.identity?.cognitoAuthenticationProvider;

  let sub: string | undefined = undefined;
  if (cognitoAuthenticationProvider) {
    const providerParts = cognitoAuthenticationProvider.split(':');
    sub = providerParts[providerParts.length - 1];
  }

  if (!sub) {
    throw new UnauthorizedError({ message: 'Unable to determine calling user' });
  }

  const { Users } = await cognito.listUsers({
    // Assumes user pool id is configured in lambda environment
    UserPoolId: process.env.USER_POOL_ID!,
    Limit: 1,
    Filter: `sub="${sub}"`,
  });

  if (!Users || Users.length !== 1) {
    throw new UnauthorizedError({ message: `No user found with subjectId ${sub}` });
  }

  return { sub, username: Users[0].Username! };
};

Con auth: 'cognito', el autorizador de Cognito User Pools de API Gateway verifica el JWT que el llamante proporciona en el encabezado Authorization y coloca las claims verificadas en el evento en event.requestContext.authorizer.claims:

import type { APIGatewayProxyEvent } from 'aws-lambda';
import { Identity } from './context.js';
import { UnauthorizedError } from './generated/ssdk/index.js';

export const getIdentity = async (
  event: APIGatewayProxyEvent,
): Promise<Identity> => {
  const claims = event.requestContext?.authorizer?.claims as
    | Record<string, string>
    | undefined;

  const sub = claims?.sub;
  const username = claims?.username;

  if (!sub || !username) {
    throw new UnauthorizedError({ message: 'Unable to determine calling user' });
  }

  return { sub, username };
};

Luego conecta el resolver al contexto en src/handler.ts:

import { Service } from './service.js';
import { getIdentity } from './identity.js';
// ...
const httpResponse = await serviceHandler.handle(httpRequest, {
  tracer,
  logger,
  metrics,
  getIdentity: () => getIdentity(event),
});

Ahora podemos usar la identidad resuelta en una operación, por ejemplo en src/operations/echo.ts:

import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';

export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
  const identity = await ctx.getIdentity();
  return { message: `${identity.username} says ${input.message}` };
};

Construcción y Generación de Código

El proyecto del modelo Smithy usa Docker para construir los artefactos Smithy y generar el SDK de servidor TypeScript:

pnpm nx build <model-project>

yarn nx build <model-project>

npx nx build <model-project>

bunx nx build <model-project>

Este proceso:

Compila el modelo Smithy y lo valida
Genera la especificación OpenAPI a partir del modelo Smithy
Crea el SDK de servidor TypeScript con interfaces de operación con seguridad de tipos
Genera artefactos de build en dist/<model-project>/build/

El proyecto backend copia automáticamente el SDK generado durante la compilación:

pnpm nx copy-ssdk <backend-project>

yarn nx copy-ssdk <backend-project>

npx nx copy-ssdk <backend-project>

bunx nx copy-ssdk <backend-project>

Objetivo de Bundle

El generador configura automáticamente un objetivo bundle que utiliza Rolldown para crear un paquete de despliegue:

pnpm nx bundle <project-name>

yarn nx bundle <project-name>

npx nx bundle <project-name>

bunx nx bundle <project-name>

La configuración de Rolldown se encuentra en rolldown.config.ts, con una entrada por cada bundle a generar. Rolldown gestiona la creación de múltiples bundles en paralelo si están definidos.

Desarrollo Local

El generador configura un servidor local con recarga en caliente:

pnpm nx serve <backend-project>

yarn nx serve <backend-project>

npx nx serve <backend-project>

bunx nx serve <backend-project>

Desplegando tu API Smithy

El generador crea infraestructura como código con CDK o Terraform según el iacProvider seleccionado.

CDK
Terraform

El constructo CDK para desplegar tu API está en la carpeta common/constructs:

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

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

Esto configura:

Una función AWS Lambda para el servicio Smithy
API Gateway REST API como disparador de la función
Roles y permisos IAM
Grupo de logs de CloudWatch
Configuración de trazado X-Ray

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

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

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

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

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

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

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

El constructo UserIdentity puede generarse usando el generador ts#website#auth

Los módulos Terraform para desplegar tu API están en la carpeta common/terraform.

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

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

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

  asset_bucket_name = module.asset_bucket.bucket_name

  # Environment variables for the Lambda function
  env = {
    ENVIRONMENT = var.environment
    LOG_LEVEL   = "INFO"
  }

  # Additional IAM policies if needed
  additional_iam_policy_statements = [
    # Add any additional permissions your API needs
  ]

  tags = local.common_tags
}

Esto configura:

Una función AWS Lambda que sirve la API Smithy
API Gateway REST API como disparador de la función
Roles y permisos IAM
Grupo de logs de CloudWatch
Configuración de trazado X-Ray
Configuración CORS

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

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

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

  asset_bucket_name = module.asset_bucket.bucket_name

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

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

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

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

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

  asset_bucket_name    = module.asset_bucket.bucket_name

  user_pool_id         = local.user_pool_id
  user_pool_client_ids = [local.client_id]

  env = {
    ENVIRONMENT = var.environment
    LOG_LEVEL   = "INFO"
  }

  tags = local.common_tags
}

El módulo Terraform provee varias salidas:

# Access the API endpoint
output "api_url" {
  value = module.my_api.stage_invoke_url
}

# Access Lambda function details
output "lambda_function_name" {
  value = module.my_api.lambda_function_name
}

WAF

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

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

CDK
Terraform

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

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

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

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

  asset_bucket_name = module.asset_bucket.bucket_name
  enable_waf        = false
}

Registro de acceso

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

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

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

CDK
Terraform

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

Puedes personalizar el formato del registro de acceso pasando deployOptions al construir tu API:

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

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

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

Integraciones

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

CDK
Terraform

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

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

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

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

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

  asset_bucket_name = module.asset_bucket.bucket_name

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

Accediendo a las integraciones

CDK
Terraform

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

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

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

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

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

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

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

# Otorgar permisos adicionales a la única función Lambda
resource "aws_iam_role_policy" "additional_permissions" {
  name = "additional-api-permissions"
  role = module.my_api.lambda_execution_role_name

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

Personalizando opciones por defecto

CDK
Terraform

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

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

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

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

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

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

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

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

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

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

  asset_bucket_name = module.asset_bucket.bucket_name

  # Configuración VPC
  vpc_subnet_ids         = [aws_subnet.private_a.id, aws_subnet.private_b.id]
  vpc_security_group_ids = [aws_security_group.lambda_sg.id]

  tags = local.common_tags
}

Personalizando opciones por operación

CDK
Terraform

Para personalizar las opciones usadas al crear la integración por defecto para operaciones específicas (sin afectar a las demás), puedes usar el método withOperationOptions. Por ejemplo, si deseas aumentar el timeout de la función Lambda para solo una operación:

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

// Las operaciones seleccionadas siguen siendo integraciones por defecto, por lo que siguen tipadas en consecuencia:
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({ ... }));

Las opciones que especificas se fusionan con las opciones de integración por defecto (y cualquier opción establecida mediante withDefaultOptions). Ten en cuenta que no puedes especificar opciones para operaciones que hayas reemplazado mediante withOverrides, ya que estas ya no usan la integración por defecto.

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

Sobrescribiendo integraciones

CDK
Terraform

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

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

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

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

const storageBucket = new Bucket(this, 'Bucket', { ... });

const apiGatewayRole = new Role(this, 'ApiGatewayS3Role', {
  assumedBy: new ServicePrincipal('apigateway.amazonaws.com'),
});

storageBucket.grantRead(apiGatewayRole);

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOverrides({
      getFile: {
        bucket: storageBucket,
        integration: new AwsIntegration({
          service: 's3',
          integrationHttpMethod: 'GET',
          path: `${storageBucket.bucketName}/{fileName}`,
          options: {
            credentialsRole: apiGatewayRole,
            requestParameters: {
              'integration.request.path.fileName': 'method.request.querystring.fileName',
            },
            integrationResponses: [{ statusCode: '200' }],
          },
        }),
        options: {
          requestParameters: {
            'method.request.querystring.fileName': true,
          },
          methodResponses: [{
            statusCode: '200',
          }],
        }
      },
    })
    .build(),
});

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

Sobrescribiendo autorizadores

CDK
Terraform

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

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

Integraciones explícitas

CDK
Terraform

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

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

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

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

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

HTTP API
REST API

# Eliminar la función Lambda única por defecto
 resource "aws_lambda_function" "api_lambda" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApiHandler"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "index.handler"
   runtime         = "nodejs22.x"
   timeout         = 30
   # ... resto de la configuración
 }

# Eliminar la integración proxy por defecto
 resource "aws_apigatewayv2_integration" "lambda_integration" {
   api_id           = module.http_api.api_id
   integration_type = "AWS_PROXY"
   integration_uri  = aws_lambda_function.api_lambda.invoke_arn
   # ... resto de la configuración
 }

# Eliminar las rutas proxy por defecto
 resource "aws_apigatewayv2_route" "proxy_routes" {
   for_each = toset(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"])
   api_id    = module.http_api.api_id
   route_key = "${each.key} /{proxy+}"
   target    = "integrations/${aws_apigatewayv2_integration.lambda_integration.id}"
   # ... resto de la configuración
 }

# Agregar funciones Lambda individuales para cada operación usando el mismo bundle
 resource "aws_lambda_function" "say_hello_handler" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-SayHello"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "sayHello.handler"  # Handler específico para esta operación
   runtime         = "nodejs22.x"
   timeout         = 30
   source_code_hash = data.archive_file.lambda_zip.output_base64sha256

   tracing_config {
     mode = "Active"
   }

   environment {
     variables = var.env
   }

   tags = var.tags
 }

 resource "aws_lambda_function" "get_documentation_handler" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-GetDocumentation"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "getDocumentation.handler"  # Handler específico para esta operación
   runtime         = "nodejs22.x"
   timeout         = 30
   source_code_hash = data.archive_file.lambda_zip.output_base64sha256

   tracing_config {
     mode = "Active"
   }

   environment {
     variables = var.env
   }

   tags = var.tags
 }

# Agregar integraciones específicas para cada operación
 resource "aws_apigatewayv2_integration" "say_hello_integration" {
   api_id           = module.http_api.api_id
   integration_type = "AWS_PROXY"
   integration_uri  = aws_lambda_function.say_hello_handler.invoke_arn
   payload_format_version = "2.0"
   timeout_milliseconds   = 30000
 }

 resource "aws_apigatewayv2_integration" "get_documentation_integration" {
   api_id           = module.http_api.api_id
   integration_type = "HTTP_PROXY"
   integration_uri  = "https://example.com/documentation"
   integration_method = "GET"
 }

# Agregar rutas específicas para cada operación
 resource "aws_apigatewayv2_route" "say_hello_route" {
   api_id    = module.http_api.api_id
   route_key = "POST /sayHello"
   target    = "integrations/${aws_apigatewayv2_integration.say_hello_integration.id}"
   authorization_type = "AWS_IAM"
 }

 resource "aws_apigatewayv2_route" "get_documentation_route" {
   api_id    = module.http_api.api_id
   route_key = "GET /documentation"
   target    = "integrations/${aws_apigatewayv2_integration.get_documentation_integration.id}"
   authorization_type = "NONE"
 }

# Agregar permisos Lambda para cada función
 resource "aws_lambda_permission" "say_hello_permission" {
   statement_id  = "AllowExecutionFromAPIGateway-SayHello"
   action        = "lambda:InvokeFunction"
   function_name = aws_lambda_function.say_hello_handler.function_name
   principal     = "apigateway.amazonaws.com"
   source_arn    = "${module.http_api.api_execution_arn}/*/*"
 }

 resource "aws_lambda_permission" "get_documentation_permission" {
   statement_id  = "AllowExecutionFromAPIGateway-GetDocumentation"
   action        = "lambda:InvokeFunction"
   function_name = aws_lambda_function.get_documentation_handler.function_name
   principal     = "apigateway.amazonaws.com"
   source_arn    = "${module.http_api.api_execution_arn}/*/*"
 }

# Eliminar la función Lambda única por defecto
 resource "aws_lambda_function" "api_lambda" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApiHandler"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "index.handler"
   runtime         = "nodejs22.x"
   timeout         = 30
   # ... resto de la configuración
 }

# Eliminar la integración proxy por defecto
 resource "aws_apigatewayv2_integration" "lambda_integration" {
   api_id           = module.http_api.api_id
   integration_type = "AWS_PROXY"
   integration_uri  = aws_lambda_function.api_lambda.invoke_arn
   # ... resto de la configuración
 }

# Eliminar las rutas proxy por defecto
 resource "aws_apigatewayv2_route" "proxy_routes" {
   for_each = toset(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"])
   api_id    = module.http_api.api_id
   route_key = "${each.key} /{proxy+}"
   target    = "integrations/${aws_apigatewayv2_integration.lambda_integration.id}"
   # ... resto de la configuración
 }

# Agregar funciones Lambda individuales para cada operación usando el mismo bundle
 resource "aws_lambda_function" "say_hello_handler" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-SayHello"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "sayHello.handler"  # Handler específico para esta operación
   runtime         = "nodejs22.x"
   timeout         = 30
   source_code_hash = data.archive_file.lambda_zip.output_base64sha256

   tracing_config {
     mode = "Active"
   }

   environment {
     variables = var.env
   }

   tags = var.tags
 }

 resource "aws_lambda_function" "get_documentation_handler" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-GetDocumentation"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "getDocumentation.handler"  # Handler específico para esta operación
   runtime         = "nodejs22.x"
   timeout         = 30
   source_code_hash = data.archive_file.lambda_zip.output_base64sha256

   tracing_config {
     mode = "Active"
   }

   environment {
     variables = var.env
   }

   tags = var.tags
 }

# Agregar recursos y métodos específicos para cada operación
 resource "aws_api_gateway_resource" "say_hello_resource" {
   rest_api_id = module.rest_api.api_id
   parent_id   = module.rest_api.api_root_resource_id
   path_part   = "sayHello"
 }

 resource "aws_api_gateway_method" "say_hello_method" {
   rest_api_id   = module.rest_api.api_id
   resource_id   = aws_api_gateway_resource.say_hello_resource.id
   http_method   = "POST"
   authorization = "AWS_IAM"
 }

 resource "aws_api_gateway_integration" "say_hello_integration" {
   rest_api_id = module.rest_api.api_id
   resource_id = aws_api_gateway_resource.say_hello_resource.id
   http_method = aws_api_gateway_method.say_hello_method.http_method

   integration_http_method = "POST"
   type                   = "AWS_PROXY"
   uri                    = aws_lambda_function.say_hello_handler.invoke_arn
 }

 resource "aws_api_gateway_resource" "get_documentation_resource" {
   rest_api_id = module.rest_api.api_id
   parent_id   = module.rest_api.api_root_resource_id
   path_part   = "documentation"
 }

 resource "aws_api_gateway_method" "get_documentation_method" {
   rest_api_id   = module.rest_api.api_id
   resource_id   = aws_api_gateway_resource.get_documentation_resource.id
   http_method   = "GET"
   authorization = "NONE"
 }

 resource "aws_api_gateway_integration" "get_documentation_integration" {
   rest_api_id = module.rest_api.api_id
   resource_id = aws_api_gateway_resource.get_documentation_resource.id
   http_method = aws_api_gateway_method.get_documentation_method.http_method

   integration_http_method = "GET"
   type                   = "HTTP"
   uri                    = "https://example.com/documentation"
 }

# Actualizar deployment para depender de nuevas integraciones
~ resource "aws_api_gateway_deployment" "api_deployment" {
    rest_api_id = module.rest_api.api_id

    depends_on = [
     aws_api_gateway_integration.lambda_integration,
     aws_api_gateway_integration.say_hello_integration,
     aws_api_gateway_integration.get_documentation_integration,
    ]

    lifecycle {
      create_before_destroy = true
    }

   triggers = {
     redeployment = sha1(jsonencode([
       aws_api_gateway_integration.say_hello_integration,
       aws_api_gateway_integration.get_documentation_integration,
     ]))
   }
  }

# Agregar permisos Lambda para cada función
 resource "aws_lambda_permission" "say_hello_permission" {
   statement_id  = "AllowExecutionFromAPIGateway-SayHello"
   action        = "lambda:InvokeFunction"
   function_name = aws_lambda_function.say_hello_handler.function_name
   principal     = "apigateway.amazonaws.com"
   source_arn    = "${module.rest_api.api_execution_arn}/*/*"
 }

 resource "aws_lambda_permission" "get_documentation_permission" {
   statement_id  = "AllowExecutionFromAPIGateway-GetDocumentation"
   action        = "lambda:InvokeFunction"
   function_name = aws_lambda_function.get_documentation_handler.function_name
   principal     = "apigateway.amazonaws.com"
   source_arn    = "${module.rest_api.api_execution_arn}/*/*"
 }

Patrón de Integración

CDK
Terraform

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

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

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

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

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

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

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

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

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

  asset_bucket_name = module.asset_bucket.bucket_name

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

Generación de Código

CDK
Terraform

Dado que las operaciones se definen en Smithy, usamos generación de código para proveer metadatos al constructo CDK para integraciones con seguridad de tipos.

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

Necesitarás ejecutar un build cada vez que cambies tu modelo Smithy para asegurar que los tipos consumidos por el constructo CDK estén actualizados.

pnpm build

yarn build

npm run build

bun build

Si estás trabajando activamente en tu infraestructura CDK y API Smithy simultáneamente, puedes usar nx watch para regenerar estos tipos cada vez que hagas cambios en el modelo:

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

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

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

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

Otorgando Acceso (Solo IAM)

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

CDK
Terraform

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

# Create an IAM policy to allow invoking the API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "MyApiInvokePolicy"
  description = "Policy to allow invoking the Smithy API"

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

# Attach the policy to an IAM role
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
}

Invocando tu API Smithy

Para invocar tu API desde un sitio web React, puedes usar el generador connection, que provee generación de cliente con seguridad de tipos a partir de tu modelo Smithy.

Conexiones

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

React a Smithy APILlama a una API Smithy desde un sitio web React

API Smithy a Base de Datos RelacionalConecta una API Smithy a una base de datos relacional Aurora

API Smithy a TypeScript DynamoDBConecta una API Smithy a una tabla DynamoDB