AWS Lambda y API Gateway: Crea tu primera API (consola y CLI)

Los comandos de este post son bash. En Windows usa WSL, Git Bash o CloudShell, que ya viene con el CLI configurado. En PowerShell el heredoc, el JSON con comillas simples y zip no funcionan igual.

Antes de empezar

Si usas tu cuenta personal de AWS con un usuario administrador, salta esta sección. Ya tienes todo.

Si estás en una cuenta de empresa, compartida, o en una de la universidad, es donde aparecen los AccessDenied.

Primero, mira con qué usuario estás autenticado.

aws sts get-caller-identity

Este tutorial toca cuatro servicios, y cada uno necesita permisos:

Son policies gestionadas por AWS. Verifica los nombres exactos en tu consola antes de pedirlas, porque algunas cambiaron de nombre con los años.

IAMFullAccess es mucho poder. Quien la tiene puede crearse los permisos que quiera, o sea que en la práctica es acceso de administrador. Para aprender está bien. Para un usuario de producción, no.

Crea la función Lambda

Debemos ir al servicio AWS Lambda y crear nuestra primera función.

Tenemos 3 opciones:

1. Author from scratch: Comenzar con un "Hello World".
2. Use a blueprint: Una plantilla o configuración preestablecida.
3. Container image: Con una imagen usando el servicio de ECR.

Voy a utilizar la opción de Author from scratch para simplemente hacer un Hello World.

Elegimos un nombre para la función y el runtime, o sea, el lenguaje en el que se va a ejecutar. Hay opciones como Node.js, Python, Java, Ruby, etc.

Ya con esto le podemos dar en Create function. Una vez creado veremos las siguientes pestañas:

En la pestaña de Code debemos escribir el código que se ejecutará cada vez que se llame a la función. Ten en cuenta que las Lambdas se cobran por dos cosas: el número de invocaciones y los GB-segundo (duración × memoria asignada).

El Always Free de AWS ofrece 1 millón de peticiones y 400,000 GB-segundos de cómputo cada mes. AWS Lambda pricing.

Lo mismo con el AWS CLI

La consola hace una cosa por debajo que el CLI no, y es crear el rol de ejecución. Así que empezamos por ahí.

# Guarda estos valores, los usaremos en todos los comandos
 
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
REGION=$(aws configure get region || echo "$AWS_REGION")

Revisa que ACCOUNT_ID y $REGION no estén vacíos. echo "$ACCOUNT_ID / $REGION". Ten en cuenta que todos estos comandos van en la misma terminal. Si la cierras, las variables se pierden.

aws iam create-role \
  --role-name lambda-hello-role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": { "Service": "lambda.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }]
  }'
 
aws iam attach-role-policy \
  --role-name lambda-hello-role \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

Si te sale un AccessDenied al crear el rol, no es que el rol no exista: es que tu usuario no tiene permiso para crear roles. El mensaje completo te dice cuál falta (is not authorized to perform: iam:CreateRole). Pasa mucho en cuentas de empresa o compartidas. Necesitas permisos de IAM, o que alguien con acceso de administrador te cree el rol.

Esa policy es la que permite escribir logs en CloudWatch. Sin ella la función corre, pero no verás nada.

Crea un archivo index.mjs con este contenido:

export const handler = async (event) => {
  return {
    statusCode: 200,
    body: "Hello from Lambda!",
  };
};

Y empaquétalo con zip:

zip function.zip index.mjs

aws lambda create-function \
  --function-name hello-lambda \
  --runtime nodejs22.x \
  --handler index.handler \
  --role arn:aws:iam::$ACCOUNT_ID:role/lambda-hello-role \
  --zip-file fileb://function.zip

Si el comando falla con un error de rol inválido, espera unos segundos y repítelo. IAM puede tardar en propagar el rol que creamos.

Y para probarla debemos ejecutar el siguiente comando:

aws lambda invoke --function-name hello-lambda response.json
cat response.json

Los runtimes disponibles cambian y los viejos se deprecan. Revisa cuál está vigente antes de copiar nodejs22.x, puedes verlos en Lambda runtimes.

Para subir cambios de código después:

zip function.zip index.mjs
aws lambda update-function-code \
  --function-name hello-lambda \
  --zip-file fileb://function.zip

Logs de las Lambdas

Para ver cómo está funcionando tu Lambda, entra a la pestaña Monitor. Si quieres ver los logs completos, ve a CloudWatch, donde podrán ver cada evento que ocurra como lo pueden ver en este video:

Lo mismo con el AWS CLI

Este comando te muestra los logs en vivo sin abrir la consola:

aws logs tail /aws/lambda/hello-lambda --follow

Para ver solo lo reciente:

aws logs tail /aws/lambda/hello-lambda --since 10m

API Gateway

Ahora vamos al servicio API Gateway y damos en Create an API.

Existen varios tipos que podemos usar:

1. HTTP API
2. WebSocket API
3. REST API
4. REST API Private

Usa HTTP API, es la v2, más simple y cuesta $1 por millón de requests contra $3.50 del REST API. Cambia a REST API solo si necesitas API keys, throttling por cliente, WAF o caching en el gateway. Verifica precios en los docs antes de publicar, además el precio depende de la región y por el tramo de volumen. Te recomiendo que leas Choose between REST APIs and HTTP APIs y Amazon API Gateway pricing.

Creación de la API Gateway

1. Le damos un nombre y el tipo de IP address type (IPv4 o Dualstack).

2. Definimos un stage, por ejemplo v1 o prod.

Un stage es una versión desplegada y con nombre de tu API. Cada una tiene su propia URL (.../v1, .../prod), su propia config (variables, logs, throttling) y apunta a un deployment distinto.

Lo mismo con el AWS CLI

Ojo con el subcomando: HTTP API es apigatewayv2, no apigateway. Si usas el segundo estás creando una REST API.

API_ID=$(aws apigatewayv2 create-api \
  --name hello-api \
  --protocol-type HTTP \
  --query ApiId --output text)
 
echo $API_ID

El stage no se crea solo por CLI. Hay que pedirlo, y con --auto-deploy para no tener que desplegar a mano cada cambio:

aws apigatewayv2 create-stage \
  --api-id $API_ID \
  --stage-name v1 \
  --auto-deploy

Conectar nuestra Lambda

Ahora en la sección de Routes del API Gateway creamos una ruta, por ejemplo GET /hello.

Una vez creada la ruta debemos conectarla con nuestra Lambda a través de las Integrations. La integración es el recurso de backend al que esa ruta llama cuando recibe una solicitud.

Existen varias opciones de integraciones, en nuestro caso debemos seleccionar la Lambda Function.

Y ya solo queda seleccionar nuestra Lambda y darle en crear.

Y listo. Ahora si vamos a nuestra ruta /hello ya nos saldrá el "Hello from Lambda!" que habíamos definido en nuestra Lambda.

La URL del API Gateway la podemos ver en el menú izquierdo donde dice API, o en la parte de Stages seleccionando un stage.

Lo mismo con el AWS CLI

Aquí son tres comandos, y el tercero es el que a todo el mundo se le olvida.

Primero la integración:

INTEGRATION_ID=$(aws apigatewayv2 create-integration \
  --api-id $API_ID \
  --integration-type AWS_PROXY \
  --integration-uri arn:aws:lambda:$REGION:$ACCOUNT_ID:function:hello-lambda \
  --payload-format-version 2.0 \
  --query IntegrationId --output text)

--payload-format-version 2.0 no es opcional en la práctica. Si lo omites, el CLI usa 1.0 y el event que recibe tu Lambda tiene otra forma que la que ves en la consola.

Luego la ruta, apuntando a esa integración:

aws apigatewayv2 create-route \
  --api-id $API_ID \
  --route-key "GET /hello" \
  --target integrations/$INTEGRATION_ID

Y el permiso. La consola lo agrega sola cuando eliges la Lambda en el dropdown; por CLI no. Si te lo saltas, la ruta responde 500 y los logs de la Lambda están vacíos, porque la Lambda nunca se llegó a ejecutar:

aws lambda add-permission \
  --function-name hello-lambda \
  --statement-id apigw-invoke-hello \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:$REGION:$ACCOUNT_ID:$API_ID/*/GET/hello"

Para obtener la URL y probar:

ENDPOINT=$(aws apigatewayv2 get-api --api-id $API_ID \
  --query ApiEndpoint --output text)
 
curl $ENDPOINT/v1/hello

El /v1 es el nombre del stage. Si tu stage se llama $default, la URL va sin prefijo.

CORS

El curl funciona. Pero un fetch() desde el navegador, no.

Esto es porque el API Gateway no manda las cabeceras de CORS por defecto, así que el navegador bloquea la respuesta. El error que ves en la consola del navegador no menciona API Gateway, y ahí es donde perdemos tiempo buscando el error.

En la consola está en el menú izquierdo, en la sección CORS de tu API.

Lo mismo con el AWS CLI

aws apigatewayv2 update-api --api-id $API_ID \
  --cors-configuration AllowOrigins="*",AllowMethods="GET"

AllowOrigins="*" sirve para probar. En algo real pon tu dominio.

Limpiar todo

Acabas de dejar una URL pública, sin autenticación, que ejecuta tu código. Cualquiera que la tenga puede invocarla. Este post no cubre autenticación, así que lo mejor es borrarlo.

Parado no te cuesta nada, pero borrar lo que ya no usas es una costumbre que te recomiendo.

El rol no se borra mientras tenga la policy adjunta.

aws apigatewayv2 delete-api --api-id $API_ID
 
aws lambda delete-function --function-name hello-lambda
 
aws iam detach-role-policy \
  --role-name lambda-hello-role \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
 
aws iam delete-role --role-name lambda-hello-role

Falta uno. delete-function no borra los logs, y el log group se queda ahí:

aws logs delete-log-group --log-group-name /aws/lambda/hello-lambda

Comments