🚀 Creando una API REST completa con AWS CDK y LocalStack: De cero a producción local

Source: Dev.to

📋 Introducción

En este tutorial completo, te mostraré cómo crear una API REST robusta para gestión de órdenes de compra usando AWS CDK, TypeScript y LocalStack. Aprenderás a configurar un entorno de desarrollo local que simula perfectamente AWS, implementar un CRUD completo y probarlo exhaustivamente.

🎯 ¿Qué vamos a construir?

• API REST completa con 5 endpoints CRUD
• Funciones Lambda en TypeScript para cada operación
• Base de datos DynamoDB para persistencia
• API Gateway como punto de entrada
• LocalStack para desarrollo local sin costos AWS
• Pruebas automatizadas y manuales

🛠️ Stack Tecnológico

• AWS CDK v2.170.0 – Infrastructure as Code
• TypeScript 5.x – Lenguaje principal
• Node.js 20+ – Runtime
• LocalStack – Simulación AWS local
• DynamoDB – Base de datos NoSQL
• API Gateway – Gestión de APIs
• Lambda – Funciones serverless

🔧 Configuración Inicial

1. Instalación de LocalStack en VS Code

📦 Instalar la Extensión LocalStack

Método 1: Desde VS Code Marketplace

1. Abre VS Code.
2. Ve a la pestaña de Extensiones (Ctrl+Shift+X o Cmd+Shift+X).
3. Busca “LocalStack”.
4. Instala la extensión oficial LocalStack por LocalStack.
5. Reinicia VS Code.

Método 2: Desde la línea de comandos

code --install-extension localstack.localstack

Método 3: Instalación manual
Visita VS Code Marketplace - LocalStack y haz clic en “Install”.

⚙️ Configuración de la Extensión

Abre la configuración (Ctrl+, en Windows o Cmd+, en Mac) y busca “LocalStack”. Añade las siguientes opciones:

{
  "localstack.endpoint": "http://localhost:4566",
  "localstack.profile": "default",
  "localstack.region": "us-east-1",
  "localstack.autoStart": true,
  "localstack.dockerFlags": "-d"
}

🎯 Características de la Extensión

• Panel de LocalStack: Estado del servicio, logs en tiempo real, gestión de servicios, explorador de recursos.
• Comandos disponibles (Paleta Ctrl+Shift+P):
  • LocalStack: Start – Iniciar LocalStack
  • LocalStack: Stop – Detener LocalStack
  • LocalStack: Restart – Reiniciar LocalStack
  • LocalStack: Show Logs – Mostrar logs
  • LocalStack: Open Web UI – Abrir interfaz web
• Integración con AWS CLI: Configuración automática de endpoints, perfiles locales, redirección de comandos AWS a LocalStack.

🔍 Verificar Instalación de la Extensión

• Panel lateral: Ícono de LocalStack en la barra lateral.
• Paleta de comandos: Ctrl+Shift+P → buscar “LocalStack”.
• Status bar: Indicador de estado en la barra inferior.

🚀 Primer Uso

1. Abre el panel LocalStack (clic en el ícono).
2. Inicia LocalStack con el botón Start LocalStack o mediante el comando.
3. Verifica que el panel muestre Running.
4. Revisa los logs en la pestaña Logs.

2. Crear el Proyecto CDK desde Cero

📋 Prerrequisitos

Asegúrate de tener instalados:

# Node.js (versión 20+)
node --version

# npm
npm --version

# AWS CDK CLI (global)
npm install -g aws-cdk

# Verificar instalación CDK
cdk --version

🏗️ Inicializar el Proyecto CDK

# Crear directorio del proyecto
mkdir cdk-api-localstask
cd cdk-api-localstask

# Inicializar proyecto CDK con TypeScript
cdk init app --language typescript

Verificar estructura inicial

ls -la
# Deberías ver:
# bin/           # Punto de entrada de la aplicación
# lib/           # Definiciones de stacks
# test/          # Tests unitarios
# package.json   # Dependencias del proyecto
# tsconfig.json  # Configuración TypeScript
# cdk.json       # Configuración CDK

Instalar dependencias adicionales

# Dependencias para LocalStack
npm install aws-cdk-local

# Dependencias para Lambda y DynamoDB
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

# Dependencias para TypeScript
npm install @types/aws-lambda @types/uuid uuid

# Dependencias de desarrollo
npm install --save-dev @types/node typescript

⚙️ Configurar Scripts para LocalStack

Edita package.json y agrega los siguientes scripts:

{
  "scripts": {
    "build": "tsc",
    "watch": "tsc -w",
    "test": "jest",
    "synth": "cdk synth",
    "deploy": "cdk deploy",
    "local:synth": "npx cdklocal synth",
    "local:deploy": "npx cdklocal deploy",
    "local:destroy": "npx cdklocal destroy",
    "local:diff": "npx cdklocal diff",
    "local:bootstrap": "npx cdklocal bootstrap"
  }
}

🔧 Configurar CDK para LocalStack

cdk.json (configuración CDK):

{
  "app": "npx ts-node --prefer-ts-exts bin/app.ts",
  "watch": {
    "include": ["**"],
    "exclude": [
      "README.md",
      "cdk*.json",
      "**/*.d.ts",
      "**/*.js",
      "tsconfig.json",
      "package*.json",
      "yarn.lock",
      "node_modules",
      "test"
    ]
  },
  "context": {
    "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
    "@aws-cdk/core:checkSecretUsage": true,
    "@aws-cdk/core:target-partitions": ["aws", "aws-cn"],
    "@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
    "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
    "@aws-cdk/aws-ecs:arnFormatIncludesClusterName": true,
    "@aws-cdk/core:validateSnapshotRemovalPolicy": true,
    "@aws-cdk/aws-codepipeline:crossAccountKeyAliasStackSafeResourceName": true,
    "@aws-cdk/aws-s3:createDefaultLoggingPolicy": true,
    "@aws-cdk/aws-sns-subscriptions:restrictSqsDescryption": true,
    "@aws-cdk/aws-apigateway:disableCloudWatchRole": false,
    "@aws-cdk/core:enablePartitionLiterals": true,
    "@aws-cdk/aws-events:eventsTargetQueueSameAccount": true,
    "@aws-cdk/aws-iam:minimizePolicies": true,
    "@aws-cdk/core:disableStackTrace": false
  }
}

📁 Crear Estructura de Directorios

# Directorios para organizar el código
mkdir -p lib/lambdas
mkdir -p lib/types

# Archivos base
touch lib/types/order.ts
touch lib/lambdas/create-order.ts
touch lib/lambdas/get-order.ts
touch lib/lambdas/list-orders.ts
touch lib/lambdas/update-order.ts
touch lib/lambdas/delete-order.ts

🎯 Configurar el Stack Principal

bin/app.ts (punto de entrada):

#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import { CdkApiLocalstackStack } from '../lib/cdk-api-localstask-stack';

const app = new cdk.App();
new CdkApiLocalstackStack(app, 'CdkApiLocalstackStack', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT || '000000000000', // LocalStack default
    region: process.env.CDK_DEFAULT_REGION || 'us-east-1',
  },
});