Módulo 4: De la consola a tu API

Tiempo estimado: 45 min

Lo que vas a construir

Primero creas una tabla de DynamoDB y una Lambda desde la consola, y compruebas que siguen separadas aunque vivan en el mismo proyecto. Después borras esa práctica y desplegamos la API de gastos completa con AWS CDK.

Parte 1: crea los recursos a mano (15 min)

Crea una tabla de DynamoDB

Guarda y observa un item

Crea y prueba una Lambda

💡 Esta Lambda usa el blueprint de la consola. La app final de infra/gastos-stack.ts usa Node.js 24.x y arm64. Aquí solo nos importa ver qué recursos crea la consola. La Lambda corre con el Node que AWS le da, no con el de tu laptop.

Ese log group apareció solo al ejecutar la función. Hasta ahora creaste todo con clics, y la consola agregó por su cuenta un execution role y un log group. Si quisieras repetir esta app en otro proyecto, tendrías que acordarte de cada opción y de cada recurso.

Limpia la práctica

npm run limpiar-practica

El comando solo conoce los nombres de esta práctica y no toca el stack gastos-hormiga.

Parte 2: los mismos recursos como código (5 min)

Si un amigo quisiera lo mismo en su proyecto, tendrías que repetir cada clic y acordarte del nombre, el runtime, la llave id y el rol. Con infraestructura como código (IaC) esos pasos quedan escritos en un archivo, y AWS crea los recursos igual cada vez. Si el archivo trae un error, también lo repite, por eso revisamos qué va a cambiar antes de desplegar.

En este workshop usamos dos capas:

• CloudFormation recibe una plantilla y crea los recursos en el orden necesario.
• AWS CDK te deja escribir esa plantilla en TypeScript. Con npm run synth ves la plantilla que genera, sin desplegar nada.

Estas son las piezas del archivo:

• Un constructo (new Table(...), new RestApi(...)): un recurso, o un grupo de recursos, que AWS debe crear.
• El id ('GastosTable'): el nombre del recurso dentro del archivo. En la tabla fijamos el logical ID con overrideLogicalId, porque si cambia, CloudFormation cree que es otra tabla y borra la que tiene tus gastos.
• Las propiedades (tableName, runtime, memorySize): las decisiones que antes tomabas con clics.
• addMethod: conecta una ruta de API Gateway, como POST /gastos, con la Lambda que la atiende.
• addToRolePolicy: lo que puede hacer la Lambda. Sin permiso para escribir en DynamoDB, la función existe pero no puede guardar nada.
• CfnOutput: los valores que nos entrega al terminar, como la URL de la API.

Lee el stack

Abre infra/gastos-stack.ts en Kiro y sigue la numeración. También lo puedes ver aquí con número de línea.

La tabla. En la línea 32 empieza GastosTable, la tabla donde viven tus gastos. La línea 33 le da un nombre basado en el stack. Con ese nombre fijo, si un cambio necesitara reemplazar la tabla, CloudFormation bloquea el deploy antes de tocar la que ya tiene tus gastos (mientras no cambies ni quites tableName).

La línea 37 explica el removalPolicy: CDK guarda las tablas aunque borres el stack, y aquí pedimos lo contrario para que npm run limpiar no deje tus gastos huérfanos.

La API. En la línea 73 está la API. ¿Por qué REST API y no HTTP API, que es más nueva y barata? Porque las API keys solo existen en REST, y las usamos para proteger el POST.

La API key. En la línea 99 se crea la key que va a mandar tu Atajo. El usage plan de las líneas 104 a 110 limita a quien trae esa key: 2 peticiones por segundo y un máximo al día, para que nadie se acabe tus créditos con un loop.

Las Lambdas. La línea 44 es la receta de una Lambda: runtime, arquitectura, memoria, log group y cómo se empaqueta el TypeScript. La línea 65 registra, y la línea 94 dice que el POST /gastos necesita API key. La que lista empieza en la línea 69. Cada una apunta a un archivo de src/handlers/, que es donde falta el código.

Los permisos. Cada Lambda recibe solo lo que usa: la línea 66 permite escribir en la tabla y la línea 70 permite leerla, nada más.

Tip 🧠: Si algo te causa curiosidad, pregúntale a Kiro. 😉

Parte 3: construye la API de gastos (25 min)

Tus Lambdas están vacías

src/handlers/registrar.ts solo responde 501, que en HTTP significa "esto todavía no está implementado". src/handlers/listar.ts está igual.

npm test tests/gastos.test.ts

Salen cinco en rojo. Cuatro son de las Lambdas vacías y los resuelve Kiro. El quinto, rechaza montos negativos, lo arreglas tú más adelante.

Pídele a Kiro la tarea 2

La tarea 2 de .kiro/specs/gastos-hormiga/tasks.md dice qué archivos tocar, cuáles no y qué tests deben pasar al final.

Haz la tarea 2 de .kiro/specs/gastos-hormiga/tasks.md

Mientras trabaja, fíjate qué archivos abre: la spec y los helpers de src/shared/.

🤖 Cuando el código lo escribe una IA, tu trabajo es revisarlo.

Revisa lo que escribió

1. ¿Usa validarGasto()? Busca validarGasto( en registrar.ts. Si Kiro escribió su propia validación, pídele que use la de src/shared/validacion.ts, que es la que vas a arreglar tú.

2. ¿La lista usa QueryCommand? En listar.ts tiene que haber un QueryCommand, no un ScanCommand. Un Scan lee la tabla completa cada vez y DynamoDB cobra por lo que lee. Con tres gastos ni lo notas, con tres mil sí.

3. ¿Instaló algo? Mira package.json en el diff. La tarea no necesita paquetes nuevos, y las reglas de .kiro/steering/npm-seguro.md le piden a Kiro avisarte antes de agregar uno.

Entiende lo que hace el código

Que los tests pasen no basta. La IA escribe las líneas, pero si mañana le entregas esta app a tu equipo, quien responde por lo que hace eres tú. Antes de seguir, usa a Kiro para entender qué pasa cuando registras y consultas un gasto.

Explícame src/handlers/registrar.ts y listar.ts como si
nunca hubiera usado DynamoDB. No cambies archivos, no
despliegues ni instales nada.

Crea un HTML sencillo fuera de este repo y ábrelo. Muestra
dos flujos:
- POST /gastos: petición, validarGasto, PutCommand y tabla.
- GET /gastos: petición, QueryCommand y respuesta JSON.

En cada paso muestra el archivo, las líneas y un fragmento
corto. Explica pk, sk, PutCommand y QueryCommand, y por qué
Query no lee toda la tabla como Scan. Usa solo lo que exista
en mis archivos.

Mientras lo lees, sigue el recorrido: qué bloque recibe el gasto, cuál lo revisa, cuál lo guarda y cuál lo lee.

Compruébalo tú

npm test tests/gastos.test.ts

Prepara tu cuenta para CDK

CDK sube el código de tus Lambdas a un bucket de S3 antes de crearlas. Ese bucket y unos roles se crean una sola vez por cuenta y Región, y a eso se le llama bootstrap.

npm run bootstrap

Crea un stack aparte, CDKToolkit, con el bucket de S3, un repositorio de ECR que no vas a usar, roles de IAM y un parámetro de SSM. Se queda después del workshop: Qué se queda en tu cuenta explica cómo borrarlo.

Despliega

npm run diff compara tu código contra lo que hay en AWS. Como todavía no hay nada, lista todo como nuevo.

npm run diff
npm run deploy

npm run deploy empaqueta tus Lambdas con esbuild, las sube al bucket y le pasa a CloudFormation la plantilla de CDK. Antes de crear nada muestra los cambios de permisos (IAM Statement Changes) y pregunta Do you wish to deploy these changes (y/n)?. Revisa que cada Lambda tenga una sola acción sobre la tabla y contesta y.

Mientras se despliega

Al terminar, npm run deploy imprime los Outputs: ApiUrl, ApiKeyId y TablaGastos.

Verifícalo tú

El script lee la URL y la key por ti, hace el POST y luego pide la lista con un GET. Funciona igual en Windows, macOS y Linux.

npm run probar

Ahí está tu café, guardado por el código que escribió tu Kiro. Puedes verlo también en DynamoDB > Explore items, en la tabla gastos-hormiga-gastos.

Para registrar otro con tus datos (monto, descripción y categoría, en ese orden):

npm run probar 28 "galleta del súper" snacks

$API = "pega-aqui-tu-ApiUrl"
$KEY = "pega-aqui-tu-api-key"
'{"monto":45,"descripcion":"cafe","categoria":"cafes"}' |
  Out-File -Encoding ascii gasto.json
curl.exe -X POST "$API/gastos" `
  -H "x-api-key: $KEY" `
  -H "x-origen: curl" `
  -H "content-type: application/json" `
  --data-binary "@gasto.json"

API="pega-aqui-tu-ApiUrl"
KEY="pega-aqui-tu-api-key"
curl -X POST "$API/gastos" \
  -H "x-api-key: $KEY" \
  -H "x-origen: curl" \
  -H "content-type: application/json" \
  -d '{"monto": 45, "descripcion": "café", "categoria": "cafes"}'

Tócale al código

Ahora te toca escribir a ti. Primero arranca el modo de desarrollo, para que guardar un archivo sea desplegarlo:

npm run sync

⚠ npm run sync (cdk watch) es solo para desarrollo: salta partes de CloudFormation para ir más rápido. Para cambios que quieras conservar, regresa a npm run deploy.

npm run probar negativo

Responde 201. Tu API acepta que te gastaste menos cincuenta pesos.

Abre src/shared/validacion.ts, que es lo que usa la Lambda de Kiro para validar el body. En la línea 19 se revisa que el monto sea número, pero nadie revisa que sea mayor a 0.

npm test tests/gastos.test.ts
npm run probar negativo

Checkpoint ✅

npm run verify 4

Revisa que pasen los tests de gastos y los de infraestructura, que sin API key responda 403, que con key responda 201, que el gasto aparezca en el GET y que tu API ya rechace los montos negativos. Los gastos de prueba que crea los borra al terminar.

Para saber más

Si te sobra tiempo

1. Agrega transporte a uno de tus gastos y mira cómo cambia el GET.
2. Haz que descripcion no pueda tener solo números. Escribe primero el test.

Si te atoraste

Pega en Kiro el último error y el comando que lo produjo, y pídele que lo explique sin desplegar ni borrar nada (más en errores comunes). Si no te ayuda, levanta la mano. Para seguir con el módulo mientras tanto:

git stash -u
git switch modulo-4
npm ci
npm run deploy

git stash -u guarda tus cambios por si los quieres de vuelta. La rama modulo-4 tiene el módulo terminado: la página de Amplify, las Lambdas escritas y la validación arreglada. Después del workshop, git stash pop recupera lo que guardaste.