GraphQL — qué es, lenguaje de consultas y aplicación en proyectos móviles

¿Qué es GraphQL?

GraphQL — es una especificación y un entorno de ejecución para API que le da al cliente control total sobre los datos que recibe. Desarrollada por ingenieros de Facebook para resolver los problemas de la aplicación móvil News Feed, la especificación fue publicada como un estándar abierto en 2015. Desde 2018, GraphQL está gestionado por la GraphQL Foundation con el apoyo de la Linux Foundation y empresas como Apollo, AWS, GitHub, SAP y otras.

A diferencia de REST, donde cada endpoint devuelve una estructura de datos fija, GraphQL utiliza un único endpoint que acepta una cadena de consulta. El cliente describe en la consulta qué campos necesita, y el servidor devuelve exactamente esos. Por ejemplo, la consulta { user(id: "1") { name email } } devolverá solo el nombre y el correo electrónico del usuario, sin campos adicionales como address, phone o createdAt que habría que obtener en REST.

GraphQL no está vinculado a ninguna base de datos o lenguaje específico. La especificación solo define el formato de las consultas y respuestas. Existen implementaciones de servidores en Node.js (graphql-js, Apollo Server), Kotlin (graphql-kotlin, Netflix DGS Framework), Python (Graphene, Strawberry), Ruby (graphql-ruby) y otros lenguajes. Las bibliotecas cliente están disponibles para todas las plataformas principales, incluyendo Apollo Client para iOS, Android y web.

Cómo funciona GraphQL

La arquitectura de GraphQL consta de tres componentes clave: Esquema (Schema), Resolutores (Resolvers) y el Motor GraphQL (GraphQL Engine). El esquema define qué tipos de datos están disponibles, qué consultas se pueden ejecutar y qué argumentos aceptan. Los resolutores son funciones del lado del servidor que devuelven datos para cada campo del esquema. El motor recibe la consulta entrante, la valida contra el esquema, llama a los resolutores correspondientes y ensambla la respuesta.

El proceso de procesamiento de una consulta es el siguiente:

• El cliente envía una solicitud POST a /graphql con un cuerpo JSON { "query": "..." }
• El servidor analiza la consulta, construye un AST (Árbol de Sintaxis Abstracta) y lo valida contra el esquema
• El motor recorre el AST, llamando a los resolutores para cada campo, recopilando datos
• La respuesta se devuelve en formato JSON, coincidiendo estrictamente con la estructura de la consulta

La ventaja clave de la arquitectura GraphQL es la resolución a nivel de campo. En REST, el desarrollador obtiene todos los campos de un recurso (posiblemente con adicionales) o recurre a extensiones como ?fields=name,email. En GraphQL, dicho filtrado está integrado en el lenguaje: cada consulta especifica explícitamente qué campos se necesitan, y el servidor devuelve exactamente esos. Esto es especialmente importante para aplicaciones móviles, donde la cantidad de datos transferidos afecta directamente la velocidad de carga y el consumo de tráfico.

Query, Mutation y Subscription

GraphQL define tres tipos de operaciones, cada una correspondiente a un escenario de interacción específico. Query — para lectura de datos, análogo a GET en REST. Mutation — para modificar datos (crear, actualizar, eliminar), análogo a POST/PUT/DELETE. Subscription — para actualizaciones en tiempo real mediante WebSocket, que no tiene un análogo directo en REST clásico (requiere soluciones adicionales como WebSocket o Server-Sent Events).

La sintaxis básica de las consultas es intuitiva:

// Query simple con argumento
query {
    user(id: "42") {
        name
        email
        avatarUrl
    }
}

// Mutation que devuelve datos modificados
mutation {
    updateProfile(name: "Ivan") {
        id
        name
        updatedAt
    }
}

// Subscription — escucha actualizaciones en tiempo real
subscription {
    newMessage(chatId: "chat_1") {
        id
        text
        sender { name }
    }
}

Query se ejecuta en paralelo — todos los campos del mismo nivel se cargan simultáneamente. Esto permite cargar datos relacionados (usuario y sus publicaciones) en una sola solicitud sin múltiples viajes de ida y vuelta. Mutation se ejecuta secuencialmente — las mutaciones en una solicitud se ejecutan una tras otra en el orden de declaración. Subscription establece una conexión persistente mediante WebSocket, a través de la cual el servidor envía datos cuando ocurre un evento.

Las operaciones pueden aceptar variables para separar los datos de la consulta, directivas (@include, @skip) para la inclusión condicional de campos y fragmentos para reutilizar conjuntos de campos. Estas capacidades hacen que las consultas GraphQL sean flexibles y reutilizables, lo que es especialmente importante en proyectos grandes con múltiples pantallas y componentes.

Esquema y sistema de tipos de GraphQL

En el corazón de GraphQL se encuentra un sistema de tipos que describe todos los datos y operaciones posibles de la API. El esquema es una descripción de los tipos que el servidor puede devolver y las consultas que acepta. El esquema se escribe en Schema Definition Language (SDL) y sirve como un contrato entre el cliente y el servidor. El cliente puede obtener el esquema mediante introspección — una consulta especial __schema que devuelve una descripción completa de la API.

Ejemplo de esquema para un blog:

// SDL — Schema Definition Language
type User {
    id: ID!
    name: String!
    email: String
    posts: [Post!]!
}

type Post {
    id: ID!
    title: String!
    content: String
    author: User!
}

type Query {
    user(id: ID!): User
    posts(page: Int): [Post!]!
}

El signo de exclamación (!) indica un campo no nulo — estará garantizadamente presente en la respuesta. Los corchetes [ ] denotan una lista. GraphQL admite tipos escalares (Int, Float, String, Boolean, ID), tipos de objeto, enum, union, interface y tipos de entrada (para argumentos de mutaciones). La tipificación estricta autodocumenta la API y permite que las herramientas del cliente generen código: tipos TypeScript, clases de datos Kotlin, estructuras Swift.

La introspección es una característica única de GraphQL ausente en REST. El cliente puede enviar una consulta al esquema y obtener una descripción completa de todos los tipos, campos, argumentos y directivas. Esto es la base de herramientas como GraphiQL y Apollo Studio, que generan automáticamente documentación y autocompletado para desarrolladores. La introspección también permite escribir pruebas automatizadas que verifican la conformidad del esquema con la estructura esperada.

Comparación de GraphQL con REST

La elección entre GraphQL y REST es una de las decisiones arquitectónicas clave al diseñar una API. Ambos enfoques tienen sus fortalezas y debilidades, y la elección depende de los requisitos específicos del proyecto. REST gana en simplicidad y universalidad, GraphQL en flexibilidad y eficiencia de consultas. Veamos la tabla comparativa.

El principal inconveniente de GraphQL es la complejidad del caché. En REST, el caché HTTP funciona a nivel de URL: una solicitud a /api/users/42 siempre devuelve la misma estructura, y la respuesta se puede almacenar en caché por URL. En GraphQL, todas las solicitudes van a un único endpoint, y la estructura de la respuesta depende del cuerpo de la solicitud. Para solucionar esto, Apollo Client utiliza un caché normalizado del lado del cliente, que divide las respuestas en entidades individuales por id y las actualiza automáticamente al recibir nuevos datos.

Otro aspecto importante es el problema N+1. Al solicitar datos anidados (por ejemplo, publicaciones de usuario y comentarios para cada publicación), GraphQL puede ejecutar una consulta SQL separada para cada elemento de la lista. Se soluciona con DataLoader — una utilidad para agrupar y almacenar en caché consultas a bases de datos, que agrupa solicitudes individuales en un lote. En REST, este problema es menos pronunciado ya que el desarrollador controla la estructura de la respuesta en el lado del servidor.

Ejemplos de consultas GraphQL

Veamos ejemplos prácticos del uso de GraphQL en una aplicación móvil con Kotlin y Apollo Client. Los ejemplos demuestran escenarios típicos: carga de datos para una pantalla de perfil (query), creación de una nueva publicación (mutation) y suscripción a nuevos comentarios (subscription). Cada ejemplo incluye tanto la consulta GraphQL como el código del lado del cliente.

Query: Carga de perfil con publicaciones

Una sola consulta GraphQL carga el usuario, sus últimas publicaciones y el número total de seguidores. En REST, esto requeriría al menos 2-3 solicitudes: /users/42, /users/42/posts, /users/42/stats. GraphQL las combina en un solo viaje de ida y vuelta, reduciendo el tiempo de carga de la pantalla en conexiones lentas.

// Consulta GraphQL (en archivo .graphql)
query ProfileScreen($userId: ID!) {
    user(id: $userId) {
        name
        bio
        avatarUrl
        posts(limit: 10) {
            id
            title
            createdAt
        }
        followersCount
        followingCount
    }
}

// Llamada en el cliente (Apollo Client + Kotlin)
val response = apolloClient
    .query(ProfileScreenQuery(userId = "42"))
    .execute()
binding.nameText.text = response.data?.user?.name

Mutation: Creación de una nueva publicación

La mutación no solo crea un recurso, sino que también devuelve sus datos actuales para actualizar la interfaz de usuario. El campo __typename es utilizado por Apollo Client para la normalización del caché — el cliente actualizará automáticamente el registro Post en el caché al recibir una respuesta exitosa de la mutación.

// Mutation GraphQL
mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) {
        id
        title
        createdAt
        author {
            id
            name
        }
    }
}

// Llamada de mutation con tipo input
val input = CreatePostInput(
    title = "Nuevo post sobre GraphQL",
    content = "GraphQL simplifica el trabajo con API..."
)
val result = apolloClient
    .mutation(CreatePostMutation(input))
    .execute()

Una ventaja importante de GraphQL sobre REST en el contexto del desarrollo móvil es la generación automática de código. Apollo Client para Kotlin (Apollo GraphQL) genera clases tipificadas seguras a partir de archivos .graphql en tiempo de compilación. Si el servidor cambia el esquema, el proyecto no se compilará hasta que se actualicen las consultas. Esto evita errores en tiempo de ejecución típicos de REST, donde los cambios en la estructura de la respuesta pueden pasar desapercibidos durante el desarrollo.

Ecosistema: Apollo, Relay y herramientas

El ecosistema de GraphQL incluye varias bibliotecas y herramientas clave que simplifican el desarrollo y la operación. Apollo Client es la biblioteca cliente más popular, compatible con React, iOS, Android y Kotlin Multiplatform. Relay de Facebook es una alternativa para aplicaciones React con un enfoque único para la gestión de datos y el almacenamiento en caché. La elección entre Apollo y Relay depende de la plataforma y los requisitos de rendimiento.

En el lado del servidor, los líderes son Apollo Server (Node.js), Netflix DGS Framework (Kotlin/Java) y graphql-ruby. Para el desarrollo de esquemas y pruebas de consultas, se utiliza GraphiQL — un IDE interactivo integrado en el navegador. Apollo Studio proporciona métricas de rendimiento, trazado de consultas y gestión de esquemas para entornos de producción. Mención aparte merece GraphQL Code Generator — una herramienta que genera tipos TypeScript, Kotlin, Swift y Dart a partir de un esquema SDL.

Para el desarrollo móvil, es de particular interés Apollo Kotlin (Apollo GraphQL) — una biblioteca completamente escrita en Kotlin con soporte para corrutinas, Flow y Multiplatform. Permite utilizar consultas GraphQL unificadas para Android e iOS en proyectos Kotlin Multiplatform. Apollo Kotlin normaliza el caché, admite errores a nivel de campo (errores parciales) y genera automáticamente modelos de datos a partir de archivos .graphql. Esto hace de GraphQL la opción preferida para grandes proyectos móviles donde la velocidad de desarrollo y la seguridad de tipos son importantes.