WR 124: GraphQL para novatos

Descubriendo GraphQL: la evolución de las API ¶

La forma en que las aplicaciones se comunican con los servidores ha cambiado poco desde que surgieron las API REST. Durante años diseñamos rutas, versiones y mecanismos de paginación para exponer datos. Hoy, esas prácticas nos exponen a dos problemas recurrentes: overfetching y underfetching. GraphQL ofrece un nuevo enfoque al definir un lenguaje de consulta preciso y flexible, liberado por Facebook en 2015, y convertido en un estándar de facto para exponer datos en distintas plataformas.

Qué es GraphQL y qué no es ¶

Antes de profundizar, conviene derribar dos mitos comunes.

• “GraphQL no es una API. GraphQL es una forma de consultar una API.”
• Tampoco es una base de datos: SQL puede invocar a equívocos, pero GraphQL no almacena información, solo la recupera bajo demanda.

En esencia, GraphQL es un lenguaje de consulta para servidores HTTP que define un esquema estático. Ese esquema describe tipos, relaciones y operaciones permitidas. A partir de él, clientes y servidores establecen un contrato sólido que:

• El cliente invoca con una sola petición HTTP (generalmente POST).
• El servidor responde con un JSON que coincide exactamente con la forma de la petición.

Principales virtudes de GraphQL ¶

Solicitar solo lo que necesitas ¶

El overfetching ocurre cuando recibes más datos de los que vas a usar. El underfetching, cuando careces de algún fragmento que tu interfaz necesita. Con GraphQL, cada consulta especifica:

• Los campos concretos a recuperar.
• El nivel de anidación deseado.
• Los filtros y argumentos requeridos.

Así se minimiza el ancho de banda y el procesado innecesario.

Un único punto de entrada ¶

En lugar de múltiples rutas REST, GraphQL expone generalmente un solo endpoint, por ejemplo:

POST /graphql

Desde él se sirve todo el esquema y las operaciones definidas: consultas, mutaciones y suscripciones.

Esquema como contrato ¶

El SDL (Schema Definition Language) permite definir tipos de forma clara:

type Person {
name: String!
age: Int
}

• String! indica que name es obligatorio.
• Int define un campo entero.

Este tipado previo dota de autocompletado y validación inmediata en herramientas como GraphiQL o Apollo Studio.

Interacción con GraphQL ¶

Consultas (query) ¶

Una consulta típica pide un conjunto de datos:

query {
allPersons {
name
age
}
}

La respuesta será un JSON con la misma estructura:

{
“data”: {
“allPersons”: [
{ “name”: “Ana”, “age”: 28 },
{ “name”: “Luis”, “age”: 34 }
]
}
}

Mutaciones (mutation) ¶

Para crear o modificar datos utilizamos mutaciones:

mutation {
createPerson(name: “Bob”, age: 36) {
name
age
}
}

El servidor devuelve la entidad recién creada, igual que un POST en REST.

Suscripciones (subscription) ¶

Las suscripciones abren una conexión persistente (WebSocket) para recibir eventos:

subscription {
newPerson {
name
age
}
}

Cada vez que alguien invoque createPerson, el servidor emitirá la nueva persona a todos los suscriptores.

Ecosistema y herramientas ¶

Clientes ¶

Para orquestar consultas y gestión de caché, validación y retries, existen librerías maduras:

• Apollo Client: autogenera consultas, gestiona fragmentos y caché.
• Relay: optimizado para React y escalable en aplicaciones de gran complejidad.
• VulcanJS: framework full-stack basado en React y GraphQL.

Servidores y resolvers ¶

En el servidor, cada campo del esquema requiere un resolver: una función que sabe cómo obtener ese dato. Por ejemplo:

const resolvers = {
Query: {
allPersons: () => db.getAllPersons()
},
Person: {
age: (person) => calculateAge(person.birthDate)
}
};

Implementar resolvers implica unir tus modelos, microservicios o bases de datos a la capa de GraphQL. Ahí reside su verdadera potencia (y complejidad inicial).

Consideraciones de seguridad ¶

Abrir un query language en tu API conlleva riesgos:

• Profundidad de consulta: evitar consultas excesivamente anidadas.
• Complejidad: penalizar operaciones que impliquen demasiado procesamiento.
• Rate limiting y timeouts: proteger el servidor de abusos.

Existen paquetes como graphql-depth-limit o graphql-query-complexity que ayudan a mitigar estos riesgos.

Arquitectura y casos de uso ¶

GraphQL funciona como una puerta unificada a múltiples fuentes:

• Bases de datos tradicionales (PostgreSQL, MongoDB).
• Microservicios y APIs legadas.
• Headless CMS (por ejemplo, GraphCMS o Directus).

Con un solo endpoint ocultas la heterogeneidad de tu backoffice y facilitas a los equipos front la tarea de iterar en interfaces sin esperar extensas coordinaciones.

Ventajas para desarrolladores ¶

• Agilidad: prototipa endpoints sin redeploys masivos.
• Visibilidad: la introspección genera documentación automática y autocompletar.
• Eficiencia: reduce llamadas HTTP y ancho de banda.
• Escalabilidad: adapta el esquema a crecer con el producto.

El siguiente paso ¶

Para dominar GraphQL, lo ideal es combinar teoría y práctica:

1. Crea un esquema básico y un playground (GraphiQL o Apollo Studio).
2. Define tipos y relaciones sencillas (por ejemplo, usuarios, posts y comentarios).
3. Implementa resolvers que conecten con tu base de datos favorita.
4. Añade mutaciones y suscripciones si tu caso lo requiere.
5. Aplica límites de profundidad y complejidad para asegurar tu API.

La curva que exige entender resolvers y arquitectura de datos compensa con creces al ganar control completo sobre lo que tu cliente obtiene de tu servidor. Cada nueva funcionalidad la defines en el esquema y, al instante, tus interfaces pueden aprovecharla sin tocar rutas ni versiones. Ese nivel de simetría entre cliente y servidor consolida proyectos más robustos y evolutivos.

La capacidad de solicitar justo lo que necesitas y proteger tu infraestructura convierten a GraphQL en un componente cada vez más común en los stack modernos. Experimenta con un prototipo hoy mismo; descubrirás cuánto más simple puede hacerse el intercambio de datos cuando tu servidor habla el lenguaje de tu interfaz.

No es una API REST, no es una base de datos. ¿Qué es GraphQL?

Lo descubriremos en el episodio de hoy.

Pero antes y como siempre quiero recomendarte mi Zona Premium, donde estamos que nos salimos con un nuevo directo de LiveCoding para que aprendas a programar mientras otros programan.

Cada semana, además, mínimo un nuevo episodio premium de Web Reactiva.

Entra y mira en premium.danielprimo.io.

100 números de la 🧨 newsletter de Web Reactiva ¶

El próximo domingo enviaré el número 100 del boletín por correo electrónico.

Será muy especial porque contaré muchos detalles sobre lo que hay “detrás de las bambalinas” de este newsletter.

Además tendrás la opción de conseguir un contenido exclusivo de regalo sin tener que hacer cabriolas en un trapecio. Sólo recomendando el newsletter podrás acceder a los números que esconde el newsletter.

¡Quiero suscribirme ya!

GraphQL para novatos ¶

Dentro de la saga no oficial para novatos de este podcast tratamos hoy una tecnología de Facebook que vive un momento de gran expansión: GraphQL.

Un lenguaje de consultas para comunicarse con una API.

Qué es un API REST y cómo construirla lo vimos en el episodio 81, que te recomiendo vivamente escuchar.

GraphQL optimiza algunos aspectos que las API REST no pueden cumplir de forma natural.

Entre otras:

• Respuestas a la medida exacta de las peticiones.
• Menor número de consultas para conseguir la información.
• Mejor adaptación a los cambios estructurales.

Facebook lo hizo a su medida ¶

Fue en 2012 cuando se conoció la existencia de GrapQL.

Una tecnología que Facebook creó para tener más fácil sus implementaciones reales.

Si lo piensas bien, tiene todo el sentido.

Aplicaciones móviles, webs y otras piezas de software, todas conectándose a la misma información.

Mucho más optimizado si todas lo hacen de la misma manera y el sistema es capaz de cumplir las demandas que exige el nuevo consumo de internet: el móvil.

Así nace GraphQL y es en 2015 cuando liberan el proyecto para su uso y disfrute.

Así es una consulta de GraphQL ¶

Durante el episodio tomamos como base los ejemplos de Core Concepts en HowToGraphQL.

Una introducción breve y concisa al SDL (Schema Definition Language), que es el nombre de la sintaxis de GraphQL.

De esta forma vemos que una query se lanza de esta manera:

{
  allPersons {
    name
  }
}

Con la que conseguiríamos una respuesta como la que sigue:

{
  "allPersons": [
    { "name": "Johnny" },
    { "name": "Sarah" },
    { "name": "Alice" }
  ]
}

Los resultados también son compatibles con JSON.

Recursos y enlaces ¶

• How to GraphQL
• Diseñando una API con Swagger
• ¿Qué es GraphQL?
• GraphQL: todos para uno y uno para todos
• ¿Por qué deberíamos abandonar REST y empezar a usar GraphQL en nuestras APIs?
• Gaphiql y Voyager (GraphQL interactivo)
• Relay y Apollo (clientes de GraphQL)
• Building a GraphQL API in PHP (código)
• VulcanJS (Full Stack Rreact+GraphQL framework)
• Awesome GraphQL

¡Nos escuchamos el próximo martes!