DEV Community: Ramses Mata

Tiempo real en aplicaciones web: Polling vs Subscriptions

Ramses Mata — Mon, 30 Mar 2026 18:48:03 +0000

En este artículo vas a entender las dos estrategias principales para mantener datos frescos en tu aplicación: Polling (tu app pregunta constantemente al servidor) y Subscriptions (el servidor avisa a tu app cuando hay cambios). Vamos a compararlas lado a lado y darte un framework para elegir la correcta según tu caso de uso. Sin atarnos a ninguna tecnología específica, los conceptos aplican ya sea que uses GraphQL, REST, WebSockets, o cualquier otro protocolo o estilo de API.

Imagina que estás usando una app de chat. Envías un mensaje y... ¿cómo sabe tu app que la otra persona ya respondió? ¿Cómo aparecen las notificaciones sin que tú hagas nada? ¿Cómo se actualizan los marcadores de un partido en vivo?

Todas estas experiencias tienen algo en común: necesitan datos frescos sin que el usuario tenga que recargar la página. A esto le llamamos tiempo real (o algo muy cercano a ello). Y hay dos formas principales de lograrlo: que tu app le pregunte al servidor constantemente si hay algo nuevo (Polling), o que el servidor le avise a tu app en el momento que algo cambia (Subscriptions).

¿Qué es Polling?

Polling es la estrategia más simple: tu aplicación le pregunta al servidor "¿hay algo nuevo?" cada cierto tiempo.

Piénsalo como cuando eras niño en un viaje largo por carretera y le preguntabas a tus papás cada 5 minutos: "¿Ya llegamos? ¿Ya llegamos? ¿Ya llegamos?" No importa si la respuesta cambió o no, tú sigues preguntando.

¿Cómo funciona?

Si eres más visual, este diagrama te puede ayudar a entender el flujo:

Tu app envía una petición al servidor (por ejemplo, cada 5 segundos)
El servidor responde con los datos más recientes
Tu app actualiza la interfaz si hay cambios
Espera el intervalo definido y repite

En JavaScript se ve algo así:

// Polling: preguntar cada 5 segundos
setInterval(async () => {
  const datos = await fetch("/api/mensajes");
  actualizarInterfaz(datos);
}, 5000);

Simple, ¿verdad? Y esa es precisamente su mayor fortaleza.

Ventajas y desventajas del Polling

Ventajas	Desventajas
Fácil de implementar: Es una petición HTTP normal en un loop	Desperdicio de recursos: Si no hay datos nuevos, la petición fue innecesaria
Funciona con cualquier infraestructura: No necesitas nada especial en el servidor	Latencia: Hay un retraso entre que el dato cambia y tu app se entera. Con un intervalo de 5s, en el peor caso tu usuario ve el dato 5 segundos tarde. Con subscriptions, la latencia típica es de ~50-150ms
Stateless: Cada petición es independiente, no hay conexiones persistentes	Carga en el servidor: Muchos clientes haciendo polling = muchas peticiones constantes
Fácil de debuggear: Puedes ver cada petición en las herramientas de desarrollo del navegador	Tradeoff del intervalo: Intervalo corto = más carga, intervalo largo = más retraso

💡 Tip importante: El intervalo de polling es una decisión de diseño clave. Un dashboard que muestra métricas cada minuto no necesita polling cada segundo. Ajusta el intervalo a lo que tu usuario realmente necesita ver.

¿Qué son las Subscriptions?

Las Subscriptions invierten el modelo: en lugar de que tu app pregunte constantemente, el servidor le avisa cuando hay algo nuevo.

Siguiendo con la analogía del viaje: en vez de preguntar "¿ya llegamos?" cada 5 minutos, le dices a tus papás "avísenme cuando lleguemos" y te pones a hacer otra cosa. Ellos te avisan solo cuando es necesario.

¿Cómo funcionan?

Si eres más visual, este diagrama te puede ayudar a ver la diferencia con polling:

Tu app establece una conexión persistente con el servidor (generalmente usando WebSockets)
Tu app le dice al servidor "avísame cuando cambien los mensajes"
El servidor mantiene esa conexión abierta
Cuando hay datos nuevos, el servidor los envía inmediatamente por esa conexión
Tu app recibe los datos y actualiza la interfaz

En JavaScript:

// Subscription: el servidor te avisa
const conexion = subscribe("/mensajes");

conexion.on("nuevoDato", (datos) => {
  actualizarInterfaz(datos);
});

Fíjate en la diferencia: no hay intervalo, no hay loop. Tu app simplemente reacciona cuando llegan datos nuevos.

Ventajas y desventajas de las Subscriptions

Ventajas	Desventajas
Tiempo real verdadero: Los datos llegan al instante, sin retraso	Más complejo de implementar: Necesitas manejar conexiones persistentes, reconexiones, y estado
Eficiente: Solo se transfieren datos cuando realmente hay cambios	Infraestructura más sofisticada: El servidor necesita soportar WebSockets o protocolos similares
Menos carga innecesaria: No hay peticiones vacías cuando nada cambió	Stateful: El servidor mantiene el estado de cada conexión activa
Mejor experiencia de usuario: La app se siente viva y responsiva	Escalabilidad diferente: Miles de conexiones abiertas simultáneas requieren planificación

💡 Tip importante: Las subscriptions no son magia, por detrás y mientras no vemos a simple vista, tecnologías como WebSockets mantienen una conexión TCP abierta entre el cliente y el servidor. Esto permite comunicación bidireccional, pero también significa que el servidor necesita gestionar el estado de cada conexión. La buena noticia es que no estamos hablando de tecnología experimental, WebSockets es soportado por más del 97% de los navegadores.

🔗 Conexión con nuestra serie: Si vienes siguiendo la serie de GraphQL, te adelanto algo: cuando implementemos subscriptions con AWS AppSync, no vamos a tener que preocuparnos por manejar WebSockets directamente. AppSync se encarga de toda esa infraestructura por nosotros: conexiones, reconexiones, escalabilidad. Nosotros solo definimos qué datos queremos escuchar.

Polling vs Subscriptions: Comparación lado a lado

Este diagrama muestra ambos modelos con el mismo escenario para que veas la diferencia de un vistazo:

Aspecto	Polling	Subscriptions
Dirección	Cliente pregunta → Servidor responde	Servidor avisa → Cliente recibe
Latencia	Depende del intervalo (segundos)	Casi instantánea (milisegundos)
Carga en servidor	Constante (aunque no haya cambios)	Solo cuando hay datos nuevos
Complejidad	Baja	Media-Alta
Infraestructura	HTTP estándar	WebSockets u otro protocolo persistente
Estado	Stateless	Stateful
Escalabilidad	Más peticiones = más carga	Más conexiones = más memoria
Debugging	Fácil (peticiones HTTP normales)	Más complejo (conexiones persistentes)

Para ponerlo en perspectiva: si tienes 1,000 usuarios conectados con polling cada 5 segundos, tu servidor recibe 12,000 peticiones por minuto aunque no haya cambiado absolutamente nada. Con subscriptions, esas 12,000 peticiones se convierten en 0 hasta que realmente haya datos nuevos.

¿Cuándo gana Polling?

Datos que cambian con poca frecuencia (dashboard de métricas diarias)
Infraestructura simple sin soporte para WebSockets
Cuando la latencia de unos segundos es aceptable
Prototipos rápidos donde la simplicidad importa más

¿Cuándo ganan las Subscriptions?

Datos que cambian constantemente (chat, colaboración en tiempo real)
La latencia baja es crítica (trading, juegos, notificaciones)
Muchos eventos por segundo donde polling sería ineficiente
Experiencias donde el usuario espera actualizaciones instantáneas

💡 Tip: La complejidad de implementar subscriptions se reduce significativamente cuando usas servicios administrados que manejan la infraestructura de WebSockets por ti.

¿Cuándo usar Polling y cuándo usar Subscriptions?

No hay un ganador universal. La mejor opción depende de tu caso de uso específico. Aquí tienes algunos ejemplos para guiarte:

Caso de uso	Enfoque recomendado	¿Por qué?
Chat en tiempo real	Subscriptions	Los usuarios esperan ver mensajes al instante
Dashboard de analytics	Polling	Los datos se actualizan cada minutos u horas
Feed de redes sociales	Polling (o híbrido)	No necesitas ver cada like al instante
Marcadores deportivos en vivo	Subscriptions	Cada segundo cuenta para la experiencia
Notificaciones	Subscriptions	El usuario espera recibirlas inmediatamente
Reporte de inventario	Polling	Se consulta periódicamente, no en tiempo real
Editor colaborativo (tipo Google Docs)	Subscriptions	Cada keystroke necesita sincronizarse

El enfoque híbrido

Algo que vale la pena mencionar: no siempre tienes que elegir uno u otro. Muchas aplicaciones usan ambos enfoques dependiendo de la funcionalidad.

Por ejemplo, una app de delivery podría usar:

Subscriptions para el tracking en tiempo real del repartidor
Polling para actualizar el catálogo de restaurantes cada cierto tiempo

La clave es preguntarte: ¿Qué tan rápido necesita mi usuario ver este cambio?

Si la respuesta es "inmediatamente" → Subscriptions
Si la respuesta es "en los próximos segundos o minutos está bien" → Polling
Si no estás seguro → Empieza con polling (es más simple) y migra a subscriptions si la experiencia lo requiere

Preguntas frecuentes

¿Qué es long polling?

Long polling es un punto intermedio entre polling y subscriptions. En vez de preguntar cada X segundos y recibir una respuesta inmediata (aunque esté vacía), tu app hace una petición y el servidor la mantiene abierta hasta que tenga datos nuevos. Cuando responde, tu app inmediatamente hace otra petición. Es más eficiente que polling tradicional pero no tan eficiente como subscriptions con WebSockets.

¿Las subscriptions consumen más recursos que polling?

Depende. Las subscriptions mantienen conexiones abiertas, lo que consume memoria en el servidor por cada cliente conectado. Polling consume ancho de banda y CPU por cada petición repetida. Con pocos usuarios y cambios frecuentes, subscriptions es más eficiente. Con muchos usuarios y cambios poco frecuentes, polling puede ser más simple de escalar.

¿Se pueden combinar polling y subscriptions?

Sí, y es más común de lo que parece. Muchas aplicaciones usan subscriptions para funcionalidades que necesitan tiempo real (como chat o notificaciones) y polling para datos que cambian con menos frecuencia (como un catálogo de productos). No tienes que elegir uno para toda tu aplicación, puedes usar el enfoque que mejor se adapte a cada funcionalidad.

Conclusión

Recapitulemos lo que aprendimos:

Polling = tu app pregunta constantemente. Simple, stateless, pero puede ser ineficiente
Subscriptions = el servidor te avisa. Eficiente y en tiempo real, pero más complejo
No hay un "ganador" cada enfoque tiene su lugar dependiendo de tu caso de uso
Los enfoques híbridos son completamente válidos y muy comunes en aplicaciones reales

La próxima vez que estés diseñando una funcionalidad que necesite datos frescos, ya tienes las herramientas conceptuales para tomar una decisión informada.

En el próximo artículo de la serie, vamos a poner estos conceptos en práctica implementando subscriptions en nuestra API de GraphQL con AWS AppSync. ¿Recuerdas toda la complejidad que mencionamos sobre manejar WebSockets, conexiones persistentes y reconexiones? AppSync se encarga de todo eso por nosotros, por debajo usa los mismos WebSockets que explicamos aquí, pero nosotros solo necesitamos definir qué datos queremos escuchar. Vamos a ver cómo pasar de la teoría a código funcionando.

AppSync: Tu primer Resolver de GraphQL

Ramses Mata — Wed, 18 Mar 2026 22:18:04 +0000

En el artículo anterior, desplegamos nuestro esquema en AWS AppSync. Creamos una API de GraphQL completa con tipos, queries y mutations perfectamente definidos. Incluso exploramos la documentación que AppSync generó automáticamente, pero hay un problema.

Si intentas hacer una query en el playground de AppSync ahora mismo, no obtendrás datos. Tu API tiene un esquema bastante cool, aunque hay un detalle; es como un restaurante con un menú increíble pero sin cocina. El menú promete platillos deliciosos, pero nadie sabe cómo prepararlos.

Hoy vamos a construir esa cocina. Vamos a implementar resolvers - las funciones que realmente responden a tus queries y mutations con datos reales.

Al final de este artículo, tendrás:

✅ Un resolver funcionando para consultar usuarios por ID
✅ Un resolver funcionando para crear nuevos usuarios
✅ Entendimiento completo del patrón para implementar cualquier resolver

Y lo mejor: haremos todo en la consola de AWS. Sin configuración local, sin instalar nada, sin complicaciones.

Si eres más visual, este diagrama te puede ayudar a entender el panorama completo de lo que construiremos:

Antes de empezar

Para seguir este tutorial necesitas:

Tu API de AppSync del artículo anterior
Una cuenta de AWS (el free tier es suficiente)
Un navegador web

Parte 1: Entendiendo los Resolvers

Antes de escribir código, entendamos qué son los resolvers y por qué los necesitamos.

¿Qué es un resolver?

Un resolver es una función que "resuelve" (responde) una query o mutation de GraphQL.

Piénsalo así:

Tu esquema es el menú del restaurante (qué platillos ofreces)
Los resolvers son las recetas (cómo preparar cada platillo)
La fuente de datos son los ingredientes (de dónde vienen los datos)

Cuando un cliente hace una query como usuario(id: "123"), GraphQL necesita saber:

¿Esta query existe en mi esquema? ✅ (validación)
¿Cómo obtengo los datos para responderla? ← Aquí entra el resolver

¿Por qué AWS Lambda?

Vamos a usar AWS Lambda para escribir nuestros resolvers por estas razones:

Serverless - No tienes que manejar servidores, actualizaciones, o escalamiento
Pay-per-use - Solo pagas por el tiempo que tu código se ejecuta. El free tier incluye $100 USD en créditos que puedes usar en Lambda y otros servicios. Ana Cunha escribió una guía completa sobre cómo funciona el nuevo Free Tier si quieres entender más sobre los créditos
Integración directa - Lambda se conecta perfectamente con AppSync
Perfecto para aprender - Te enfocas en la lógica de tu resolver, no en infraestructura

Queries vs Mutations

Hoy implementaremos dos tipos de resolvers:

Query resolver (usuario(id)) - Para leer datos. No cambia nada en tu sistema.
Mutation resolver (crearUsuario) - Para escribir datos. Cada ejecución crea algo nuevo.

💡 Tip importante: Usaremos datos mock (hardcodeados) en lugar de una base de datos real. Esto nos permite enfocarnos en entender cómo funcionan los resolvers sin la complejidad de configurar DynamoDB. El patrón que aprendas hoy funciona igual con una base de datos real - solo cambias de dónde vienen los datos.

Parte 2: Creando tu primer Lambda Function (Query Resolver)

Vamos a crear el resolver para la query usuario(id). Este resolver recibirá un ID y devolverá los datos de ese usuario.

En este video, creamos la función Lambda desde cero en la consola de AWS, escribimos el código del resolver y lo desplegamos:

Aquí está el código del resolver para que lo copies:

// Datos mock - en una aplicación real, estos vendrían de una base de datos
const usuarios = [
  {
    id: "1",
    nombre: "Ana García",
    email: "ana@example.com",
    fotoPerfil: "https://example.com/ana.jpg",
    creadoEn: "2024-01-15T10:30:00Z"
  },
  {
    id: "2",
    nombre: "Carlos López",
    email: "carlos@example.com",
    fotoPerfil: "https://example.com/carlos.jpg",
    creadoEn: "2024-02-20T14:20:00Z"
  }
];

export const handler = async (event) => {
  // AppSync envía los argumentos de la query en event.arguments
  const { id } = event.arguments;

  // Buscamos el usuario por ID
  const usuario = usuarios.find(u => u.id === id);

  // Retornamos el usuario encontrado, o null si no existe
  return usuario || null;
};

Entendiendo el código

Los datos mock: Creamos un array con dos usuarios. En producción, esto vendría de DynamoDB, RDS, o cualquier base de datos.

export const handler: Esta es la función que Lambda ejecuta cuando se invoca. El async significa que puede hacer operaciones asíncronas (como llamar a una base de datos).

event.arguments: AppSync empaqueta los argumentos de tu query (en este caso, el id) en event.arguments. Así es como tu resolver sabe qué usuario está pidiendo el cliente.

return usuario || null: Si encontramos el usuario, lo retornamos. Si no, retornamos null. En GraphQL, retornar null para datos que no existen es normal y esperado.

💡 Tip importante: Cuando alguien hace la query usuario(id: "1"), AppSync automáticamente toma ese id: "1" y lo pone en event.arguments.id. No tienes que hacer nada especial - AppSync lo hace por ti.

Parte 3: Conectando Lambda a AppSync

Ahora que tenemos nuestra función Lambda lista, necesitamos conectarla a AppSync. Para esto necesitamos tres cosas:

Un rol de IAM - para darle permiso a AppSync de invocar Lambda
Un Data Source - para conectar AppSync con Lambda
Un Resolver - para decirle a AppSync "cuando alguien pida usuario, usa este data source"

Creando el rol de IAM

AWS usa roles para controlar qué servicios pueden hacer qué. Necesitamos crear un rol que le dé permiso a AppSync para invocar nuestras funciones Lambda.

En este video, creamos el rol de IAM y le adjuntamos los permisos necesarios:

💡 ¿Por qué necesitamos un rol? Los servicios de AWS no pueden simplemente llamarse entre sí - necesitan permiso explícito. Este rol le da a AppSync permiso para invocar tus funciones Lambda. Lo bueno es que puedes reutilizar este mismo rol para todas tus funciones Lambda de GraphQL.

Creando el Data Source

Un data source es la forma en que AppSync se conecta a donde viven tus datos. En nuestro caso, es Lambda.

En este video, agregamos nuestra función Lambda como data source en AppSync:

💡 ¿Qué es un Data Source? Un data source puede ser Lambda, DynamoDB, un endpoint HTTP, o incluso otra API de GraphQL. AppSync usa el data source para saber a dónde ir a buscar los datos cuando recibe una query.

Adjuntando el Resolver a la Query

Ahora le decimos a AppSync que cuando alguien haga la query usuario(id), use nuestro data source de Lambda.

En este video, adjuntamos el resolver a la query usuario en el esquema. Usamos VTL (Velocity Template Language) como runtime y configuramos los mapping templates:

Aquí están los mapping templates para que los copies:

Request mapping template:

{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "arguments": $util.toJson($context.arguments)
    }
}

Response mapping template:

$util.toJson($context.result)

💡 ¿Qué son los mapping templates? Son plantillas que transforman datos entre AppSync y tu data source. El request template empaqueta los argumentos de la query (como el id) en un formato que Lambda entiende. El response template toma lo que Lambda retorna y lo formatea para GraphQL.

💡 ¿Unit resolver vs Pipeline resolver? Un unit resolver trabaja con una sola fuente de datos (nuestro caso). Un pipeline resolver puede combinar múltiples fuentes de datos en secuencia. Para este tutorial, unit resolver es perfecto.

Parte 4: Probando tu Primer Resolver

¡Es momento de ver tu resolver en acción! Vamos a hacer una query real y ver datos reales de vuelta.

Copia esta query en el playground de AppSync:

query GetUsuario {
  usuario(id: "1") {
    id
    nombre
    email
    fotoPerfil
    creadoEn
  }
}

En este video, ejecutamos la query y experimentamos con diferentes IDs y campos:

Fíjate en algo interesante: cuando pides un usuario que no existe (como id: "999"), recibes null en lugar de un error.

💡 ¿Por qué null y no un error? En GraphQL, retornar null para datos que no existen es normal y esperado. Los errores son para cuando algo sale MAL (como si Lambda fallara o no tuviera permisos), no para "dato no encontrado". Esta es una distinción importante.

Parte 5: Segundo Resolver - Mutation (crearUsuario)

Ya sabes cómo crear un resolver para leer datos. Ahora vamos a crear uno para escribir datos. El proceso es el mismo patrón que ya aprendiste:

Crear función Lambda
Crear data source en AppSync
Adjuntar resolver con mapping templates
Probar

Aquí está el código del resolver para la mutation:

// En una aplicación real, esto guardaría en una base de datos
export const handler = async (event) => {
  // Las mutations envían los datos en event.arguments.input
  const { nombre, email, fotoPerfil } = event.arguments.input;

  // Generamos un ID simple (en producción, usarías UUID o un ID de base de datos)
  const id = Date.now().toString();

  // Creamos el objeto del nuevo usuario
  const nuevoUsuario = {
    id,
    nombre,
    email,
    fotoPerfil: fotoPerfil || null,
    creadoEn: new Date().toISOString()
  };

  // En una aplicación real, aquí guardarías en la base de datos
  console.log("Usuario creado:", nuevoUsuario);

  // Retornamos el usuario creado
  return nuevoUsuario;
};

Los mapping templates son los mismos que usamos para la query:

Request mapping template:

{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "arguments": $util.toJson($context.arguments)
    }
}

Response mapping template:

$util.toJson($context.result)

Y esta es la mutation para probar en el playground:

mutation CrearUsuario {
  crearUsuario(input: {
    nombre: "María Rodríguez"
    email: "maria@example.com"
    fotoPerfil: "https://example.com/maria.jpg"
  }) {
    id
    nombre
    email
    creadoEn
  }
}

En este video, creamos la función Lambda, la conectamos a AppSync (reutilizando el rol de IAM) y probamos la mutation:

💡 ¿Por qué event.arguments.input? Las mutations usan Input Types para agrupar todos los datos que se envían. En lugar de event.arguments.nombre, event.arguments.email, etc., todo viene agrupado en event.arguments.input. Esto mantiene las mutations limpias y organizadas.

💡 ¿Por qué los datos no se guardan? Recuerda que estamos usando datos mock para aprender. Cada invocación de Lambda es independiente - no hay base de datos guardando los usuarios. En futuros artículos podríamos agregar DynamoDB para hacerlo persistente.

Parte 6: Reto Práctico

Ya conoces el patrón completo para crear resolvers. Ahora es tu turno de practicar.

Tu reto: Implementa los resolvers restantes usando el mismo patrón que aprendiste:

Resolvers de query:

publicacion(id: ID!): Publicacion - Crea datos mock con 2-3 publicaciones, busca por ID
publicaciones: [Publicacion!]! - Retorna todas las publicaciones (no necesita argumentos)

Resolver de mutation:

crearPublicacion(input: CrearPublicacionInput!): Publicacion - Extrae titulo, contenido, autorId del input, genera ID y creadoEn

Tips para completar el reto:

Sigue exactamente el mismo patrón: Lambda → Data Source → Resolver → Test
Empieza con publicaciones (es la más simple, no tiene argumentos)
Reutiliza el rol AppSyncLambdaRole para todos los data sources
Los mapping templates son los mismos para todos los resolvers
Prueba cada resolver en el playground antes de pasar al siguiente

💡 ¿Te atoras? Es normal. Revisa los pasos que seguimos para usuario y crearUsuario. El patrón es idéntico, solo cambian los nombres de los campos y la estructura de los datos.

Conclusión

Lo que lograste hoy:

✅ Creaste tu primera función Lambda para un resolver de GraphQL
✅ Conectaste Lambda a AppSync como data source
✅ Implementaste un resolver de query (usuario)
✅ Implementaste un resolver de mutation (crearUsuario)
✅ Probaste ambos en el playground de GraphQL
✅ Aprendiste un patrón que puedes repetir para cualquier resolver

La idea clave: Los resolvers son simplemente funciones que retornan datos en la forma que tu esquema define. Ya sea que uses datos mock, una base de datos, o una API externa, el patrón es el mismo.

¿Qué sigue? Tu API funciona, pero ¿qué pasa cuando los datos cambian? ¿Tu app debería preguntar por actualizaciones cada cierto tiempo (polling)? ¿O el servidor debería enviar actualizaciones automáticamente (subscriptions)? En el próximo artículo exploraremos ambos enfoques y te ayudaremos a elegir el correcto para tu caso de uso.

Planificar antes de codear: Spec Driven Development en práctica

Ramses Mata — Sat, 14 Mar 2026 00:24:47 +0000

Cuando estaba en la universidad, lo primero que hacía cuando tenía una idea nueva para un proyecto era abrir VS Code y empezaba a escribir código. ¿Te suena familiar?

El problema es que mis proyectos crecían sin dirección, cambiaba cosas constantemente, nunca sabía cuándo estaba "listo", hacía código que ni yo entendía dos semanas después y terminaba como un proyecto más que no volvía a retomar. Y desde mi punto de vista no era un problema de habilidad técnica puesto que sabía hacer las cosas, tiempo después entendí que era un problema de proceso.

Si vas comenzando tu carrera en tecnología y te pasa algo parecido, está bien, todos empezamos así. Pero hay una manera que puede funcionarte mejor.

En este artículo vamos a usar Kiro para llevar una idea desde casos de uso hasta código funcional. Si es tu primera vez con Kiro y prefieres empezar con algo más introductorio, Ana Cunha escribió una guía de primeros pasos que te puede servir como punto de partida.

El verdadero problema no es el código

En mi experiencia, muchos de mis proyectos no fallaron por código malo. Fallaron porque nunca definí bien el problema que quería resolver.

Imagina que quieres construir una aplicación que compare tu CV con una oferta de trabajo usando IA y te diga qué te falta. ¿Por dónde empiezas? ¿El frontend? ¿La base de datos? ¿La integración con inteligencia artificial?

En algún punto de mi carrera fui freelancer y en esa experiencia fue cuando le di valor a mis clases de ingeniería de software. Aprendí algo que cambió mi forma de construir: el código no es el punto de partida, es la consecuencia. Antes de escribir una sola línea, necesitas entender qué estás construyendo y para quién.

Casos de uso: Tu plano antes de construir

Un caso de uso es simplemente una descripción de cómo un usuario interactúa con tu sistema. Piénsalo como los planos de un arquitecto, no construyes una casa sin ellos, y no deberías empezar a codear sin entender qué estás construyendo.

Si quieres profundizar en la definición formal, hay documentación excelente al respecto. Pero para lo práctico, lo que necesitas son tres cosas:

Historias de usuario: Qué quiere hacer el usuario y por qué
Criterios de aceptación: Cómo sabes que funciona correctamente
Entidades y relaciones: Qué "cosas" existen en tu sistema y cómo se conectan

Volvamos al ejemplo del comparador de CVs. Una idea vaga como "quiero una app que analice mi CV" se convierte en algo concreto cuando la escribes como historia de usuario:

Como persona que busca trabajo, quiero subir mi CV en formato PDF o texto, para que el sistema pueda analizarlo y compararlo con una oferta de trabajo.

De repente, ya sabes varias cosas: necesitas soportar PDF y texto, necesitas una descripción de trabajo como segunda entrada, y el resultado es una comparación. Eso es mucho más útil que "hacer una app de CVs".

Y cuando agregas criterios de aceptación, las cosas se ponen aún más claras:

CUANDO un usuario sube un PDF, EL SISTEMA DEBE extraer el contenido correctamente
CUANDO un usuario intenta subir un formato no soportado, EL SISTEMA DEBE mostrar un error con los formatos válidos

Ahora no solo sabes qué construir, sino cuándo está "listo". Eso es algo que como estudiante nunca tenía claro.

Spec Driven Development: El puente entre la idea y el código

Definir casos de uso es el primer paso. Pero, ¿cómo pasas de esos requisitos a código real sin perderte en el camino?

Aquí es donde entra el concepto de Spec Driven Development, un enfoque donde primero diseñas las especificaciones de lo que vas a construir y después implementas. Esta metodología se divide en cuatro fases:

1. Capturar la intención: Defines qué quieres construir en lenguaje natural. Aquí es donde entran las historias de usuario y los criterios de aceptación que vimos antes. El objetivo es que cualquier persona (técnica o no) entienda qué se va a construir.

2. Traducir la intención en un blueprint del sistema: Tomas esos requisitos y los conviertes en un diseño técnico: qué componentes necesitas, cómo se comunican entre sí, qué tecnologías vas a usar. Es el plano de tu arquitectura.

3. Generar unidades de trabajo: Divides ese diseño en tareas concretas e incrementales. Cada tarea debe ser pequeña, clara y debe resultar en algo funcional que puedas probar.

4. Implementar y validar: Ahora sí, escribes código. Pero cada tarea que implementas se valida contra los criterios de aceptación que definiste en la primera fase. Así sabes que lo que construyes es lo que necesitas.

💡 Nota: Este no es un proceso que haces una sola vez. Cada que agregas una nueva feature a tu proyecto, vuelves a recorrer las cuatro fases. Defines la intención de esa feature, actualizas el blueprint, generas las unidades de trabajo y las implementas. Es un ciclo que se repite, y cada iteración se vuelve más natural.

Lo interesante de este enfoque es que no depende de ninguna herramienta específica, puedes hacerlo con un documento de texto, una pizarra, o una servilleta. Lo importante es el proceso de pensar antes de codear.

Dicho esto, herramientas como Kiro implementan esta metodología y te ayudan a recorrer las fases de manera estructurada. Kiro sigue un flujo de tres fases (1. requirements, 2. design y 3. tasks) que se mapea directamente con lo que acabamos de ver:

Fase de SDD	Qué pasa	En Kiro
Capturar la intención	Describes tu idea en lenguaje natural	Le dices a Kiro qué quieres construir
Blueprint del sistema	Requisitos + Diseño + Tareas	Kiro genera `requirements.md`, `design.md` y `tasks.md`
Unidades de trabajo	Ejecutar las tareas	Corres cada task desde el IDE
Implementar y validar	Código + validación	Kiro implementa y tú validas contra los criterios de aceptación

Pero la metodología funciona con o sin herramientas. Kiro simplemente hace el proceso más rápido.

💡 Tip importante: Las herramientas de IA no reemplazan tu pensamiento crítico. Lo amplifican. No se trata de documentar por documentar, se trata de pensar antes de codear. La documentación es el resultado de ese pensamiento.

SDD en acción: Construyendo el comparador de CVs

Para que esto no se quede en teoría, veamos cómo se ve este proceso aplicado al proyecto del comparador de CVs.

Fase 1: Capturar la intención

Aquí es donde todo lo que vimos antes cobra sentido. En lugar de abrir Kiro con un prompt vago como "hazme una app de CVs", primero escribí un archivo con las historias de usuario y criterios de aceptación que ya había definido el contexto del proyecto, quién es el usuario, qué necesita hacer y cómo sabemos que funciona. Algo así:

## Contexto del Proyecto
**Usuario principal:** Personas que buscan trabajo activamente
**Objetivo:** Mejorar la calidad del CV para fortalecer el perfil profesional

### Historia 1: Subir CV para análisis
**Como** persona que busca trabajo
**Quiero** subir mi CV en formato PDF o texto
**Para** que el sistema pueda analizarlo y compararlo con ofertas de trabajo

**Criterios de aceptación:**
CUANDO un usuario sube un archivo CV en formato PDF
EL SISTEMA DEBE extraer el contenido del documento correctamente
...

Ese archivo fue el punto de partida para Kiro. El trabajo previo de pensar el problema es lo que le da a la herramienta el contexto necesario para generar algo útil.

Fase 2: Blueprint del sistema

A partir de los casos de uso, Kiro generó tres documentos que juntos forman el blueprint completo del proyecto:

requirements.md: Kiro tomó las historias de usuario y las expandió en un documento de requisitos formal. Agregó un glosario con los términos del dominio (como "Brecha_Crítica" o "Generador_Recomendaciones"), detalló los criterios de aceptación de cada historia, e incluso identificó requisitos técnicos que no estaban explícitos en las historias originales, como la extracción de texto de PDFs y el análisis estructurado de descripciones de trabajo.

design.md: Con los requisitos claros, Kiro generó el diseño técnico: un diagrama de arquitectura con todos los componentes, los flujos de datos (cómo viaja un PDF desde el navegador hasta el análisis con IA), las interfaces entre componentes (qué recibe y qué retorna cada Lambda), y una estrategia de manejo de errores. Aquí es donde la idea se convirtió en un plano técnico concreto.

tasks.md: Finalmente, Kiro descompuso el diseño en tareas incrementales. Cada tarea referencia los requisitos que implementa, tiene subtareas claras, y construye sobre la anterior. Por ejemplo: primero la infraestructura (SAM template), después la Lambda de presigned URLs, luego la extracción de PDF, y así sucesivamente hasta tener la aplicación completa.

Un detalle interesante: Kiro inicialmente me sugirió usar Python para las funciones Lambda. Pero a mí personalmente me gusta mucho Rust, así que le pedí que cambiara el diseño para usar Rust en el backend. Y lo hizo sin problema, ajustó la arquitectura, las dependencias y las tareas. Esto es importante: la herramienta propone, pero tú decides. Si hay algo que quieres hacer diferente, experimentar con un lenguaje que te interesa o usar una tecnología que quieres aprender, puedes hacerlo. El blueprint se adapta a tus decisiones, no al revés.

El resultado fue una arquitectura clara:

Un frontend en Astro (un framework web moderno), funciones serverless en Rust desplegadas con AWS Lambda (funciones que se ejecutan bajo demanda sin manejar servidores), análisis de CVs con Amazon Bedrock (acceso a modelos de IA generativa) y almacenamiento temporal en Amazon S3 (almacenamiento de objetos en la nube). Todo definido antes de escribir la primera línea de código.

Fase 3: Ejecutar unidades de trabajo

Con el blueprint listo, pasé a ejecutar las tareas directamente desde el IDE de Kiro. En el video ejecuto la primera tarea. Kiro creó el monorepo, inicializó el frontend en Astro, configuró el workspace de Rust y generó el template.yaml base para SAM.

A partir de ahí, el plan de implementación tenía 21 tareas que iban construyendo la aplicación de forma incremental: primero la infraestructura en AWS (S3, Cognito, API Gateway, Lambdas), después las funciones backend una por una (presigned URLs, extracción de PDF, integración con Bedrock, parseo de respuestas), luego todo el frontend (autenticación, carga de CV, página de resultados), y al final el despliegue. Cada tarea referenciaba los requisitos que implementaba, así que en todo momento sabías qué estabas construyendo y por qué.

El resultado: una aplicación funcional donde subes tu CV, pegas una oferta de trabajo, y el sistema te dice qué tan compatible eres y qué te falta. Todo construido a partir de seis historias de usuario escritas en un archivo de texto.

El cambio que haría si pudiera volver

Si pudiera regresar a cuando comencé a construir mis primeras aplicaciones, lo primero que cambiaría es esto: dejaría de abrir el editor como primer paso.

No porque codear esté mal, obvio; al final es lo que nos apasiona. Sino porque dedicar aunque sea 30 minutos a pensar en qué vas a construir antes de cómo, te ahorra horas de frustración después.

Si este enfoque te resulta útil y quieres platicar sobre cómo aplicarlo en tu proyecto, encuéntrame en LinkedIn.

Recursos

Spec Driven Development - Kiro
Cómo comenzar con Kiro: Tu guía de primeros pasos - Si quieres un tutorial más paso a paso para empezar con Kiro, Ana Cunha escribió esta guía
Kiro
AWS Free Tier - Empieza sin gastar nada

AppSync: Creando y desplegando tu API en menos de 10 minutos

Ramses Mata — Wed, 04 Mar 2026 18:13:37 +0000

En el artículo anterior, diseñamos un esquema completo para nuestra API de red social. Definimos tipos para Usuario, Publicacion y Comentario, estructuramos nuestras queries y mutations, y creamos un contrato claro de lo que nuestra API puede hacer.

Pero ese esquema está solo en un archivo en tu computadora. Hoy vamos a cambiar eso.

En este artículo, vas a desplegar tu esquema en AWS AppSync (un servicio administrado de GraphQL) y verlo funcionando en vivo. Al final, tendrás:

✅ Una API de GraphQL desplegada en la nube
✅ Un endpoint que puedes compartir
✅ Documentación generada automáticamente
✅ Un playground para probar queries

Y lo mejor: lo haremos en menos de 10 minutos, sin escribir código de backend.

Antes de empezar

Para seguir este tutorial necesitas:

Tu archivo schema.graphql del artículo anterior
Una cuenta de AWS (el free tier es suficiente)
Un navegador web

¿No tienes cuenta de AWS? No te preocupes, crearla es gratis y toma solo unos minutos. Ana Cunha escribió una guía completa sobre cómo empezar con AWS sin gastar nada que te explica todo sobre el Free Tier.

Parte 1: Entendiendo tus opciones

Antes de desplegar, hablemos brevemente de las diferentes maneras de correr una API de GraphQL. No vamos a profundizar en cada una, pero es importante que sepas qué opciones existen.

Opciones self-hosted (tú manejas el servidor)

Apollo Server y GraphQL Yoga son las opciones más populares. Tú instalas el servidor, lo configuras, y lo despliegas donde quieras (AWS, Google Cloud, tu propia computadora, etc.).

Ventajas:

Control total sobre todo
Puedes correrlo en cualquier lugar
El software es open source y gratuito

Desventajas:

Tú manejas el servidor, las actualizaciones, el escalamiento
Necesitas conocimientos de DevOps
Más tiempo de setup
Pagas por la infraestructura donde lo despliegues

Opciones managed o serverless (alguien más maneja el servidor)

En este caso, un proveedor de nube (como AWS, Google Cloud, etc.) se encarga de toda la infraestructura por ti. Tú solo te enfocas en tu código y lógica de negocio.

AWS AppSync, Hasura, y Stepzen son servicios que manejan toda la infraestructura por ti. Tú solo subes tu esquema y defines tu lógica.

Ventajas:

Sin servidores que mantener
Escalamiento automático
Features incluidos (real-time, caching, etc.)

Desventajas:

Menos control
Dependes del proveedor
El modelo de precios varía según el proveedor (revisa la documentación de precios de cada servicio para tu caso específico)

¿Por qué AppSync para esta serie?

Elegimos AWS AppSync por tres razones:

Serverless - No tienes que preocuparte por servidores
Perfecto para aprender - Te enfocas en GraphQL, no en infraestructura
Real-time incluido - Lo usaremos en un próximo artículo para subscriptions

💡 Tip importante: No existe una opción "mejor" para todos los casos. AppSync es excelente tanto para aprender como para producción. Tu elección entre opciones self-hosted o managed dependerá de tus necesidades específicas de control, experiencia del equipo y preferencias de arquitectura.

Parte 2: ¿Qué es AWS AppSync?

Como mencioné brevemente, AWS AppSync es un servicio administrado de GraphQL. Ahora veamos con más detalle qué significa esto y qué hace por ti.

Piénsalo como un "GraphQL-as-a-Service": tú defines el esquema y la lógica, AppSync maneja todo lo demás.

Lo que AppSync hace por ti

Hosting del esquema - Tu esquema vive en la nube, siempre disponible
Ejecución de queries - Procesa las queries que llegan a tu API
WebSockets para real-time - Subscriptions funcionan automáticamente
Caching - Respuestas más rápidas sin configuración extra
Endpoint de API - Una URL que tus clientes pueden usar

Lo que tú controlas

Tu esquema - Defines qué datos existen y cómo se relacionan
Tus resolvers - La lógica que obtiene los datos (lo haremos en el artículo 4)
Cómo retornas datos - Usaremos mock data para aprender

El flujo de trabajo con AppSync

Hoy nos enfocaremos en los pasos 1 y 2. Los resolvers los dejamos para el siguiente artículo.

Parte 3: Desplegando tu esquema

Ahora sí, manos a la obra. Vamos a desplegar tu esquema paso a paso.

Paso 1: Abre la consola de AWS AppSync

Ve a https://console.aws.amazon.com/appsync
Si te pide iniciar sesión, usa tu cuenta de AWS
Asegúrate de estar en la región que prefieras (yo uso us-east-1)

¿Primera vez en AWS? La interfaz puede parecer abrumadora, pero no te preocupes. Solo vamos a usar AppSync, nada más.

Paso 2: Crea tu API

Haz clic en el botón naranja "Create API"
Verás dos opciones: GraphQL API y Events API. Selecciona "GraphQL API"

Ahora verás una sección llamada "API type" con dos opciones:
- GraphQL APIs ← Selecciona esta
- Merged APIs

Después de seleccionar "GraphQL APIs", verás opciones de templates. Selecciona "Design from scratch"
Haz clic en "Next"

💡 ¿Por qué GraphQL API y no Events API? Events API es para casos de uso específicos de eventos. Nosotros queremos una API de GraphQL tradicional.

💡 ¿Por qué GraphQL APIs y no Merged APIs? Merged APIs es para combinar múltiples APIs en una sola. Como estamos empezando, queremos una API simple.

💡 ¿Por qué "Build from scratch"? Porque ya tenemos nuestro esquema del artículo anterior. Las otras opciones son templates que AppSync ofrece, pero nosotros queremos usar el nuestro.

Paso 3: Configura tu API

Ahora verás un formulario con varias secciones. Vamos paso a paso:

Sección 1: API details

API name: Social-Media-API (o el nombre que prefieras)

¿Qué poner en API name? Usa algo descriptivo. Este nombre solo lo verás tú en la consola, no afecta el funcionamiento de tu API.

Deja todo lo demás como está y haz clic en "Next".

Sección 2: Specify GraphQL resources

Aquí AppSync te pregunta si quieres conectar una fuente de datos ahora o después. Verás un mensaje que dice:

"Your API can connect to one or more data sources like Amazon DynamoDB, Amazon OpenSearch, Amazon Aurora, AWS Lambda, Amazon EventBridge, or any HTTP API. You can add your data source later or optionally use this step to generate a GraphQL type backed by a DynamoDB table."

Vamos a elegir Create GraphQL resources later ya que nosotros tenemos nuestro esquema diseñado del artículo anterior. No necesitamos que AppSync genere uno por nosotros. Además, en esta serie usaremos mock data, no DynamoDB.

Haz clic en "Next".

Sección 3: Review and create

Ahora verás un resumen de todo lo que configuraste:

API type: GraphQL APIs
API name: Social-Media-API
GraphQL resources: Create later

Revisa que todo esté correcto y haz clic en "Create API".

¡Felicidades! Acabas de crear tu primera API de GraphQL en AppSync. Ahora vamos a subirle el esquema.

Paso 4: Sube tu esquema

Ahora estás en el dashboard de tu API. Verás dos secciones principales con información sobre los próximos pasos.

En el menú lateral izquierdo, haz clic en "Schema"

Verás un editor de texto grande con algunos comentarios por defecto. Aquí es donde va tu esquema.

Abre tu archivo schema.graphql del artículo anterior
Borra los comentarios que están por defecto en el editor de AppSync
Copia todo el contenido del archivo
Pégalo en el editor de AppSync
Haz clic en el botón naranja "Save Schema" en la esquina superior derecha

💡 ¿Qué pasa si ves errores? AppSync valida tu esquema automáticamente. Si hay algún error de sintaxis, te lo mostrará en rojo. Revisa que hayas copiado todo el esquema correctamente.

Si todo está bien, verás un mensaje de confirmación: "Schema saved successfully"

¡Excelente! Tu esquema ya está desplegado en la nube. AppSync lo validó, lo procesó, y ahora está listo para usarse.

Parte 4: Explorando tu API desplegada

Ahora que tu esquema está en AppSync, vamos a explorar qué generó automáticamente para ti.

Tu endpoint de API

En el menú lateral, haz clic en "Settings"
Busca la sección "API URL" o "GraphQL endpoint"
Verás una URL que se ve algo así: https://xxxxxxxxxx.appsync-api.us-east-1.amazonaws.com/graphql

Esta es la URL de tu API. Cualquier cliente de GraphQL puede usarla para hacer queries y mutations. Por ahora, solo tú tienes acceso (hablaremos de autenticación en futuros artículos).

Documentación auto-generada

Volvamos a explorar algo increíble de GraphQL: la documentación se genera automáticamente desde tu esquema.

En el menú lateral, haz clic en "Queries"
Verás un editor de queries (lo usaremos en un momento)
En la esquina superior derecha del editor, busca un botón o ícono que diga "Docs" o tenga un símbolo de libro 📖

Haz clic en "Docs" y se abrirá un panel lateral

¿Qué ves aquí?

Todos tus tipos: Usuario, Publicacion, Comentario
Tus queries: usuario, publicacion, publicaciones
Tus mutations: crearUsuario, crearPublicacion, crearComentario
Los campos de cada tipo con sus tipos de datos

Esto es introspección en acción. GraphQL permite que cualquier cliente "pregunte" sobre el esquema. Así es como herramientas como este playground saben qué campos existen y pueden darte autocompletado.

Explorando un tipo

En el panel de documentación:

Haz clic en el tipo "Usuario"
Verás todos sus campos: id, nombre, email, fotoPerfil, publicaciones, creadoEn
Nota que cada campo muestra su tipo: String!, [Publicacion!]!, etc.

¿Por qué esto es importante?

No necesitas documentación separada que se desactualice
El esquema ES la documentación
Cualquier cambio en el esquema se refleja inmediatamente aquí
Los desarrolladores que usen tu API pueden explorarla sin preguntarte

Parte 5: ¿Qué sigue?

Has llegado lejos. Veamos qué tienes ahora y qué nos falta.

Lo que ya tienes ✅

Esquema desplegado - Tu contrato de API está en la nube
Endpoint de API - Una URL que los clientes pueden usar
Documentación automática - Generada desde tu esquema
Playground para probar - El editor de queries está listo

Lo que nos falta ⏳

Resolvers - La lógica que retorna datos
Datos para consultar - Por ahora, las queries retornarían null

¿Por qué no probamos queries ahora?

Porque sin resolvers, todas las queries retornarían null o errores. Sería como tener un restaurante con menú pero sin cocina. El menú (esquema) está listo, pero necesitamos la cocina (resolvers) para servir comida (datos).

En el próximo artículo

En la Parte 4 de esta serie, vamos a:

Entender qué son los resolvers - El puente entre tu esquema y tus datos
Implementar resolvers con TypeScript - Código con type safety
Usar mock data - Datos de prueba para ver resultados inmediatos
Probar queries reales - Ver tu API funcionando de verdad
Implementar mutations - Crear usuarios, publicaciones y comentarios

Después de ese artículo, podrás hacer queries como esta y obtener resultados reales:

query {
  publicaciones {
    contenido
    autor {
      nombre
    }
    comentarios {
      contenido
    }
  }
}

Antes del próximo artículo

Te recomiendo:

Explora la documentación - Familiarízate con el panel de Docs
Revisa tu esquema - Asegúrate de que tiene todo lo que necesitas
Guarda tu API endpoint - Lo necesitarás después

Conclusión

Hoy diste un paso importante: llevaste tu esquema de un archivo local a una API desplegada en la nube.

Lo que lograste

✅ Entendiste las opciones para correr GraphQL APIs
✅ Conociste AWS AppSync y qué hace por ti
✅ Creaste tu primera API en AppSync
✅ Desplegaste tu esquema
✅ Exploraste la documentación auto-generada

El viaje hasta ahora

Parte 1: Introducción a GraphQL - Entendimos qué es y por qué usarlo
Parte 2: Diseño del esquema - Creamos nuestro contrato de API
Parte 3: Deployment (este artículo) - Desplegamos el esquema en AppSync
Próximo: Implementación de resolvers - Haremos que la API funcione

Tu API está lista para el siguiente paso

Tienes una API de GraphQL desplegada con:

Un esquema validado
Documentación automática
Un endpoint público (protegido por ahora)
Todo listo para agregar resolvers

En el próximo artículo, le daremos vida a esta API. Implementaremos los resolvers que harán que tus queries y mutations realmente funcionen.

Por ahora, celebra este logro. Pasaste de un archivo de texto a una API en la nube. Eso no es poca cosa. 🚀

Recursos

GraphQL: Diseñando tu primer esquema

Ramses Mata — Wed, 25 Feb 2026 17:07:04 +0000

GraphQL ha sido una tecnología que ha revolucionado el mundo de las APIs y muchas empresas están usando esta tecnología. Si no sabes qué es GraphQL, en mi artículo anterior hablé de esta tecnología, qué es, qué pretende resolver e introduje un pequeño ejemplo que vamos a ver más a detalle en esta serie.

En esta serie de seis artículos, vamos a construir una API de GraphQL completa desde cero. Dividiremos el proceso en las siguientes partes:

GraphQL: Una introducción para nuevos desarrolladores - Qué es GraphQL y qué problemas resuelve
Diseño del esquema (este artículo) - Diseñaremos el contrato de nuestra API
Creando y desplegando tu API - Desplegaremos el schema en AWS AppSync
Implementando resolvers con TypeScript - Construiremos la lógica de queries y mutations
Real-time en aplicaciones web: Polling vs Subscriptions - Entenderemos las opciones para datos en tiempo real
Implementando Subscriptions con AppSync - Agregaremos actualizaciones en vivo a nuestra API

Hoy nos enfocaremos en la parte más fundamental: el diseño del esquema. Como aprendiste en el artículo anterior, el esquema es como un contrato entre el cliente y el servidor que define qué datos están disponibles y cómo están estructurados. Un buen diseño de esquema es crucial para crear una API que sea fácil de usar, mantener y escalar.

Trabajando hacia atrás desde los requisitos del negocio

Antes de escribir una sola línea de código, necesitamos entender el problema que estamos tratando de resolver. Podemos pensar nuestro esquema de GraphQL como un lenguaje compartido entre los miembros de tu equipo, para construir un buen esquema, piensa en el lenguaje que usas para describir tu negocio.

Sigamos con el ejemplo del artículo anterior, en el cual estábamos construyendo una red social. Si fuésemos un usuario de una red social como las que usamos a diario probablemente definiríamos nuestra app de la siguiente manera:

Nuestra aplicación necesita por lo menos:

Perfiles de usuario con información básica
Publicaciones que los usuarios pueden crear
Comentarios en las publicaciones

Basándonos en esto podemos deducir algunas entidades:

Usuario
Publicación
Comentario

Y también las relaciones que pueden tener entre ellos.

Un Usuario puede crear muchas Publicaciones
Un Usuario puede crear muchos Comentarios
Una Publicación puede tener muchos Comentarios

Si eres más visual, este diagrama te puede ayudar a entender mejor cómo se relacionan estas entidades:

Ahora que entendemos nuestro negocio, las entidades involucradas y cómo se relacionan entre ellas, podemos comenzar a pensar en cómo representarlas en GraphQL.

Diseño del esquema y mejores prácticas

Cada entidad principal será un Type, las acciones (crear una publicación, comentar, dar me gusta) serán Mutations, las consultas (obtener el perfil, feed de publicaciones) serán Queries y las actualizaciones en tiempo real serán Subscriptions.

Antes de sumergirnos en la implementación, vamos a revisar algunas buenas prácticas que nos ayudarán a crear esquemas robustos y mantenibles:

Usa PascalCase para tipos, interfaces y uniones (ejemplo: Usuario, Publicacion, Comentario)
Usa camelCase para campos y argumentos (ejemplo: fotoPerfil, creadoEn)
Marca campos como no nulos con ! solo cuando realmente lo sean
Usa tipos escalares apropiados (Int, Float, String, Boolean, ID)

Ahora definamos nuestro esquema GraphQL. Pondremos todo en un solo archivo, lo cual funciona bien para proyectos de este tamaño. Conforme un esquema crece, es común dividirlo en varios archivos para mejor organización — eso lo veremos en futuros blog posts.

Construyendo nuestro esquema paso a paso

Antes de empezar, una nota práctica: los esquemas de GraphQL se escriben en archivos con extensión .graphql usando algo llamado SDL (Schema Definition Language). Es un lenguaje específico para definir esquemas, similar a cómo JSON tiene su propia sintaxis.

Para este proyecto, pondremos todo en un solo archivo llamado schema.graphql. Conforme tu esquema crezca, podrás dividirlo en múltiples archivos organizados por dominio o funcionalidad — pero para aprender, un solo archivo es perfecto.

Ahora sí, empecemos con nuestro primer tipo.

Paso 1: Definiendo el tipo Usuario

Empecemos con la entidad más básica: el usuario. Recordemos que en nuestros requisitos dijimos que un usuario necesita tener un perfil con nombre, foto y biografía.

type Usuario {
  id: ID!
  nombre: String!
  email: String!
  fotoPerfil: String
  creadoEn: String!
}

💡 Tip importante: Usa ! solo cuando estés 100% seguro de que el campo siempre tendrá un valor. Si tienes dudas, déjalo opcional. Es más fácil hacer un campo obligatorio después que lidiar con errores porque marcaste algo como obligatorio cuando no debía serlo.

Pero espera... ¿no dijimos que un usuario puede tener muchas publicaciones? Agreguemos esa relación:

type Usuario {
  id: ID!
  nombre: String!
  email: String!
  fotoPerfil: String
  publicaciones: [Publicacion!]!
  creadoEn: String!
}

Aquí pasa algo interesante con publicaciones: [Publicacion!]!:

publicaciones es un campo que retorna una lista de publicaciones
[Publicacion!]! significa: "una lista que nunca es nula, que contiene Publicaciones que nunca son nulas"

Paso 2: Definiendo el tipo Publicacion

Ahora que tenemos usuarios, necesitamos que puedan crear publicaciones. Una publicación necesita contenido, saber quién la escribió, y poder tener comentarios.

type Publicacion {
  id: ID!
  contenido: String!
  autor: Usuario!
  comentarios: [Comentario!]!
  creadoEn: String!
}

¿Recuerdas el problema N+1 del artículo anterior?

Con REST teníamos que hacer:

GET /api/usuarios/123 - Obtener el usuario
GET /api/usuarios/123/publicaciones - Obtener sus publicaciones
GET /api/publicaciones/456/comentarios - Obtener comentarios de cada publicación
GET /api/usuarios/789 - Obtener info del autor de cada comentario

Con GraphQL, gracias a que autor retorna un Usuario completo y comentarios retorna [Comentario!]!, podemos hacer todo en una sola query. Ya veremos cómo en un momento.

Paso 3: Definiendo el tipo Comentario

Los comentarios son la última pieza de nuestras entidades principales. Un comentario necesita saber qué dice, quién lo escribió, y a qué publicación pertenece.

type Comentario {
  id: ID!
  contenido: String!
  autor: Usuario!
  publicacion: Publicacion!
  creadoEn: String!
}

Navegación bidireccional

Fíjate en algo interesante:

Publicacion tiene un campo comentarios que retorna [Comentario!]!
Comentario tiene un campo publicacion que retorna Publicacion!

Esto significa que puedes navegar en ambas direcciones. Si tienes una publicación, puedes obtener sus comentarios. Si tienes un comentario, puedes obtener su publicación. Esta flexibilidad es uno de los superpoderes de GraphQL.

Paso 4: Input Types - Preparando para las Mutations

Ahora que tenemos nuestras entidades, necesitamos definir cómo se crearán. Para esto, GraphQL usa algo llamado Input Types. Son como moldes que definen qué información necesitas enviar cuando quieres crear o modificar algo.

input CrearUsuarioInput {
  nombre: String!
  email: String!
  fotoPerfil: String
}

input CrearPublicacionInput {
  contenido: String!
  autorId: ID!
}

input CrearComentarioInput {
  contenido: String!
  publicacionId: ID!
  autorId: ID!
}

¿Por qué necesitamos Input Types separados?

Fíjate que CrearUsuarioInput es diferente a Usuario. ¿Por qué no usar el mismo tipo?

Cuando creas un usuario, no tienes id ni creadoEn (el servidor los genera)
Cuando consultas un usuario, sí necesitas esos campos
Los Input Types solo incluyen lo que el cliente debe enviar

💡 Nota importante: En el próximo artículo veremos cómo usar estos Input Types en Mutations para crear usuarios, publicaciones y comentarios. Por ahora, solo estamos definiendo la estructura.

Paso 5: Definiendo las Queries - ¿Qué podemos consultar?

Las Queries son las operaciones de lectura de tu API. Son como las preguntas que puedes hacerle a tu sistema: "¿Quién es este usuario?" o "¿Cuáles son las últimas publicaciones?"

type Query {
  usuario(id: ID!): Usuario
  publicacion(id: ID!): Publicacion
  publicaciones: [Publicacion!]!
}

¿Qué estamos definiendo?

usuario(id: ID!): Usuario - Buscar un usuario específico por su ID. Puede retornar null si no existe.
publicacion(id: ID!): Publicacion - Buscar una publicación específica por su ID.
publicaciones: [Publicacion!]! - Obtener todas las publicaciones. Siempre retorna una lista (aunque esté vacía).

¿Por qué usuario puede ser null pero publicaciones no?

Cuando buscas un usuario por ID, puede que no exista, entonces retornas null. Pero cuando pides todas las publicaciones, siempre puedes retornar una lista (aunque esté vacía []). Es más predecible para quien usa tu API.

Paso 6: Definiendo las Mutations - ¿Qué podemos modificar?

Las Mutations son las operaciones de escritura de tu API. Son las acciones que cambian el estado de tu sistema: crear usuarios, publicar contenido, comentar.

type Mutation {
  crearUsuario(input: CrearUsuarioInput!): Usuario!
  crearPublicacion(input: CrearPublicacionInput!): Publicacion!
  crearComentario(input: CrearComentarioInput!): Comentario!
}

¿Por qué las Mutations retornan el objeto creado?

Esto es una convención muy útil en GraphQL. Cuando creas algo, inmediatamente obtienes el objeto completo de vuelta, incluyendo campos que el servidor generó (como id y creadoEn). Así el cliente no necesita hacer una query adicional para obtener esa información.

¿Por qué usamos input en lugar de parámetros sueltos?

Compara estas dos opciones:

# ❌ Parámetros sueltos (difícil de mantener)
crearUsuario(nombre: String!, email: String!, fotoPerfil: String): Usuario!

# ✅ Input Type (fácil de extender)
crearUsuario(input: CrearUsuarioInput!): Usuario!

Si mañana necesitas agregar un campo nuevo (como biografia), con Input Types solo modificas CrearUsuarioInput sin romper la firma de la mutation.

El esquema completo

Ahora que hemos construido cada pieza paso a paso, veamos cómo luce nuestro esquema completo:

type Usuario {
  id: ID!
  nombre: String!
  email: String!
  fotoPerfil: String
  publicaciones: [Publicacion!]!
  creadoEn: String!
}

type Publicacion {
  id: ID!
  contenido: String!
  autor: Usuario!
  comentarios: [Comentario!]!
  creadoEn: String!
}

type Comentario {
  id: ID!
  contenido: String!
  autor: Usuario!
  publicacion: Publicacion!
  creadoEn: String!
}

input CrearUsuarioInput {
  nombre: String!
  email: String!
  fotoPerfil: String
}

input CrearPublicacionInput {
  contenido: String!
  autorId: ID!
}

input CrearComentarioInput {
  contenido: String!
  publicacionId: ID!
  autorId: ID!
}

type Query {
  usuario(id: ID!): Usuario
  publicacion(id: ID!): Publicacion
  publicaciones: [Publicacion!]!
}

type Mutation {
  crearUsuario(input: CrearUsuarioInput!): Usuario!
  crearPublicacion(input: CrearPublicacionInput!): Publicacion!
  crearComentario(input: CrearComentarioInput!): Comentario!
}

Conclusión

Hemos diseñado un esquema completo de GraphQL trabajando hacia atrás desde nuestros requisitos de negocio. Empezamos identificando las entidades principales (Usuario, Publicacion, Comentario), definimos sus relaciones, y estructuramos las operaciones que nuestra API necesita soportar.

Lo más importante que aprendimos:

El esquema es un contrato - Define exactamente qué puede hacer tu API antes de escribir una línea de código de implementación
Piensa en relaciones, no en IDs - GraphQL brilla cuando retornas objetos completos en lugar de solo identificadores
Usa ! con intención - Solo marca campos como obligatorios cuando realmente lo sean
Input Types separan entrada de salida - Facilitan la evolución de tu API sin romper clientes existentes

En el próximo artículo de esta serie, vamos a desplegar este esquema en AWS AppSync y lo veremos funcionando con datos de prueba. Podrás hacer queries reales y ver tu API en acción, todo sin escribir una sola línea de código de backend todavía.

Por ahora, tienes un esquema sólido que sirve como documentación viva de lo que tu API puede hacer. Y eso, en sí mismo, ya es un gran paso.

GraphQL: Una introducción para nuevos desarrolladores.

Ramses Mata — Wed, 18 Feb 2026 18:06:04 +0000

¿Qué es GraphQL?

GraphQL es una herramienta con la cual aplicaciones pueden comunicarse entre ellas, estableciendo de manera concreta, reglas y patrones que le permiten saber a las dos partes (cliente y servidor) qué información puede ser transferida, en qué formato, tipos de datos, etc.

Este lenguaje de consultas lo desarrolló Meta (antes Facebook) originalmente, aunque ahora es totalmente Open Source, es desarrollado y ampliamente usado por una gran comunidad de desarrolladores.

La solución tradicional: REST APIs

Una API (Application Programming Interface) es la parte de una aplicación que le permite comunicarse con otra diferente. REST (Representational State Transfer) es una manera de diseñar APIs y ha sido un estándar por más de una década. En REST todo se trata como si fuera un recurso (un usuario, un post o un producto) y utilizamos métodos HTTP (GET, POST, PUT, DELETE) para interactuar con esos recursos.

Por ejemplo, imagina que estuvieras construyendo una red social y necesitaras la siguiente información:

Detalles del usuario (nombre, foto de perfil)
Sus últimas 3 publicaciones
De cada publicación los top 2 comentarios
Por cada comentario, el nombre y la foto de perfil del usuario que comenta

Para obtener esta información (generalmente y dependiendo de la implementación) tendríamos que hacerlo en múltiples pasos.

1. Primero, obtener la información del usuario

Petición: GET /api/usuarios/123
Respuesta:

2. Después obtendríamos sus publicaciones:

Petición: GET /api/usuarios/123/publicaciones?limit=3
Respuesta:

3. Por cada publicación tendríamos que obtener sus comentarios:

GET /api/publicaciones/456/comentarios?limit=2
GET /api/publicaciones/457/comentarios?limit=
GET /api/publicaciones/458/comentarios?limit=2

4. Por cada comentario tendríamos, que obtener la información de cada usuario para desplegar su foto y su nombre

GET /api/usuarios/456
GET /api/usuarios/789
...

El problema de este ejemplo es conocido como el problema n + 1 y es un reto clásico cuando se trabaja con REST APIs. El hacer muchas peticiones no solo puede traer problemas de rendimiento, sino también de documentación.

Ahora veamos cómo GraphQL funciona y cómo puede ayudar a resolver estos problemas.

Entendiendo GraphQL

Podemos decir que GraphQL es una manera más precisa de comunicarse con APIs, en el ejemplo de un restaurante en lugar de ordenar platillos en la carta, tú le dices al chef exactamente que ingredientes quieres en tu platillo.

Conceptos clave

1. Esquema (Schema): Toda GraphQL API empieza con un esquema, el esquema lo podemos ver como un contrato que define qué datos están disponibles y cómo están estructurados.

2. Querys: Las Querys de GraphQL lucen muy parecido a la información que tú esperas recibir, por ejemplo si hicieras la siguiente query:

Esto regresaría el siguiente JSON con exactamente esa información:

3. Querys dentro de otras querys: Un súper poder de GraphQL es su habilidad para pedir información de tipos de datos que están dentro de otros tipos.

Esto es lo que hace a GraphQL poderoso cuando lo comparamos con REST, ¿recuerdas el ejemplo que veíamos anteriormente en el cuál hacíamos un montón de peticiones usando REST? ese ejemplo se podría ver de la siguiente manera en una simple query de GraphQL:

4. Un solo Endpoint: A diferencia de REST que utiliza muchísimos endpoints GraphQL usualmente solo utiliza uno, usando múltiples Querys con la información necesaria.

5. Suscripciones: GraphQL no solo nos permite pedir información si no también recibir actualizaciones en tiempo real, usando algo llamado Suscripciones.

En nuestra red social de ejemplo, si los usuarios estuviesen leyendo alguna publicación, podríamos suscribirnos a esa publicación, para saber cuándo, un usuario hace un nuevo comentario, de esta manera podemos actualizar la pantalla en tiempo real.

Conclusión

En conclusión ahora sabes qué es GraphQL y qué intenta solucionar; no solo es hacer menos peticiones, sino que también el esquema (Schema) actúa como una manera de documentar el alcance de tu API. A pesar de que en este ejemplo mostramos las ventajas de GraphQL sobre REST, lo cierto es que no existe una herramienta que resuelva absolutamente todo, cada una tiene su uso y la persona responsable de seleccionar estas herramientas debe tomar en cuenta los pros y contras de cada una según la situación.

Muchas veces los desarrolladores nos emocionamos con nuevas tecnologías y queremos implementarlas en donde sea con tal de poner en practica lo que aprendemos, pero, lo que he aprendido con el tiempo es que, primero debemos entender el problema que queremos resolver y al final elegir la herramienta que mejor lo resuelva.

Link al siguiente artículo.

AWS IoT Core Starter with Esp32, MQTT, Rust & Terraform

Ramses Mata — Tue, 23 Sep 2025 19:00:53 +0000

Introduction

Most ESP32 + AWS IoT Core examples/tutorials use the Arduino framework and rely on manually clicking through the AWS console. That approach works for quick demos, but it quickly becomes confusing and error-prone—especially if you need to reproduce the setup or scale to multiple devices.

I recently created a repository that makes it much easier to get ESP32 devices securely talking to AWS IoT Core with Infrastructure-as-Code, and modern firmware written in Rust using the Espressif ESP-IDF framework.

Prerequisites

The tools needed to get this example working are described in the repository
Basic understanding of the MQTT protocol
Basic understanding of terraform
Clone the repository

git clone https://github.com/RamMaths/aws-iot-esp32-example.git

What we are going to build

Instead of another “hello world” demo, the goal here is to create a minimal but extensible template for ESP32 devices communicating with AWS IoT Core.

Step 1: Subscribe to Topics

In MQTT, a topic works like a communication channel between devices and services.

ESP32 devices subscribe to the topic: esp32/1
AWS IoT Core Test Client subscribes to the topic: esp32/2

This setup ensures that:

Commands sent from the test client on esp32/1 will be received by the ESP32 devices.
Device responses published to esp32/2 will be received by the test client.

Step 2: Publish a Command from the Test Client

Next, we use the AWS IoT Test Client to publish a message in JSON format to the topic esp32/1.

{
    "message": "ping"
}

The message field contains the command we want the ESP32 device to execute.
In this example, we send "ping".
The firmware listens for this value and matches it against predefined actions (e.g., respond with "pong").

Using JSON keeps the communication simple and extensible—you can later add more fields or new commands without changing the overall structure.

Step 3: Device Response

When an ESP32 device receives a command, the firmware matches it against predefined actions.

For the ping command, the device responds by publishing:

{
  "message": "pong"
}

to the topic esp32/2.
Since the test client is subscribed to this topic, it immediately receives the response.

🔧 This example only implements a simple ping → pong workflow, but this project is designed to be extensible. For example, if a device subscribed to esp32/light, you could add commands like:

{ "message": "on" }
{ "message": "off" }

Acquiring cloud resources

With the repository cloned and the terraform CLI installed, we can now provision the required AWS IoT Core resources.

1. Initialize Terraform

Navigate into the Terraform directory and initialize the project:

cd terraform
terraform init

👉 Make sure your AWS credentials are configured (aws configure) before proceeding.

2. Configure Variables

Copy the example variables file:

cp terraform.tfvars.example terraform.tfvars

Open terraform.tfvars and edit the things array. Each thing represents an IoT device in AWS IoT Core. For each device, you define:

name: the device identifier in AWS IoT
topic_prefix: the MQTT topic namespace the device can publish/subscribe to

Example configuration for two ESP32 devices (S3 and C3):

# Terraform variables for AWS IoT ESP32 Example
# Copy this file to terraform.tfvars and customize the values

# List of IoT Things to create with their configurations
things = [
  {
    name         = "esp32s3"
    topic_prefix = "esp32"
  },
  {
    name         = "esp32c3"
    topic_prefix = "esp32"
  }
]

# AWS region where IoT resources will be created
region = "us-east-1"

# Tags to apply to all AWS resources
tags = {
  Project     = "ESP32-IoT-Example"
  Environment = "development"
  ManagedBy   = "terraform"
  Owner       = "your-name"
}

3. Apply Terraform

Finally, deploy the resources:

terraform plan
terraform apply

This will create:

IoT Things for each device (esp32s3, esp32c3)
Certificates and policies (automatically downloaded into certs/)
Topic permissions based on the prefixes you specified

✅ At this point, your AWS environment is fully provisioned and ready for your ESP32 devices to connect securely.

Compiling the Firmware

With the cloud resources provisioned by Terraform, the next step is to configure, build, and flash the ESP32 firmware.

1. Configure the Project

Navigate into the firmware directory for your ESP32 variant:

After terraform creates the resources it will output something like this

cd firmware/example

(See the README setup guide for details on configuring Xtensa vs RISC-V targets.)

2. Create `cfg.toml`

Terraform outputs the connection details you need. Your config should look like this:

[example]
# Wi-Fi Configuration
wifi_ssid = "YOUR_WIFI_NETWORK"
wifi_pass = "YOUR_WIFI_PASSWORD"
mqtt_url = "mqtts://your-endpoint.iot.region.amazonaws.com"
mqtt_client_id = "thing_name"
mqtt_topic_pub = "topic_prefix"
mqtt_topic_sub = "topic_prefix"
cert_ca = "certs/AmazonRootCA1.pem"
cert_crt = "certs/[certificate-id]-certificate.pem.crt"
cert_key = "certs/[certificate-id]-private.pem.key"

Replace wifi_ssid and wifi_pass with your network credentials.
Set mqtt_topic_pub = "esp32/2" and mqtt_topic_sub = "esp32/1".
Leave the rest as generated by Terraform.

Save this as cfg.toml inside your firmware project.

3. Copy Certificates

Copy the certificates for your device into the firmware directory. The folder must be named certs:

cp -r ../../terraform/certs/thing_name ./certs

4. Build and Flash

Now compile and flash the firmware to your ESP32:

cargo build --release
cargo espflash ./path/to/the/binary -p /path/to/your/esp32/port
cargo espmonitor /path/to/your/esp32/port

What to Expect in the Logs

Once the ESP32 connects to Wi-Fi and establishes an MQTT session with AWS IoT Core, you should see logs similar to the following:

I (1234) example: WiFi connected successfully
I (1235) example: MQTT client created successfully
I (1236) example: Subscribed to topic "esp32/1"
I (1237) example: Starting main application loop

These messages confirm that:

Your device joined the Wi-Fi network
The MQTT client was initialized correctly
The subscription to the expected topic succeeded
The application is now running and ready to handle messages

Common Errors

It’s normal to briefly see messages like:

Failed to subscribe to topic "esp32/1": {}, retrying...

This happens while AWS IoT validates the certificates and sets up the secure connection. As long as the retries eventually succeed and you see the subscription message, your setup is working correctly.

🎉 Congratulations!

If you’ve followed along to this point, you’ve come a long way — from setting up cloud resources with Terraform, to configuring certificates, flashing firmware, and seeing your ESP32 securely connect to AWS IoT Core. That’s a huge achievement! 🚀

Thank you for reading and coding along. I hope you not only got things working but also learned something new about how ESP32, MQTT, and AWS IoT fit together.

🧑‍💻 What’s Next? Experiment!

This repository is meant as a starting point. Feel free to dive in and make it your own:

Add more commands beyond the simple ping → pong demo
Explore how the Wi-Fi connection is established in startup.rs
Take a closer look at our generalized MQTT client in client.rs
- It runs a separate thread to keep listening for messages
- Uses crossbeam_channel to forward messages to the main thread safely
Experiment with publishing structured JSON commands or even sensor data

🔧 Extending the Main Loop

Inside main.rs, you’ll find the main loop where incoming MQTT messages are matched against commands. Right now it only handles "ping". Here’s where you can extend it:

match msg.message.as_str() {
    "ping" => {
        info!("Ping received, sending pong");
        JsonMessage {
            message: format!("pong from: {}", app.config.mqtt_client_id),
        }
    }
    "light_on" => {
        info!("Turning light ON");
        JsonMessage {
            message: "Light is now ON".to_string(),
        }
    }
    "light_off" => {
        info!("Turning light OFF");
        JsonMessage {
            message: "Light is now OFF".to_string(),
        }
    }
    _ => {
        warn!("Unknown action: {}", msg.message);
        JsonMessage {
            message: format!("Unknown action: {}", msg.message),
        }
    }
}

You can use this pattern to hook up any device action — toggling GPIO pins, controlling peripherals, or sending structured responses back to AWS IoT Core.

🙌 Thank You

Thanks again for reading. Now go ahead — experiment, break things, fix them again, and build something awesome. That’s where the real learning happens.

If you found this helpful:

⭐ Star the repository on GitHub to support the project
💬 Share your feedback, questions, or improvements in the repo’s Discussions/Issues
🚀 Show off what you’ve built with this template — I’d love to see your projects!