Introducción a GraphQL con ejemplos prácticos (NodeJS y Go)

El problema con las RESTAPIs y modelos de datos estáticos.

Imaginemos que somos una Red Social (como Facebook) y necesitamos poder mostrar el perfil de un usuario en un dispositivo móvil o en una página web. En la página web mostraríamos todos los datos del usuario ya que tenemos lugar en pantalla… Peeeeero, si estamos en un smartphone no tenemos mucho espacio disponible así que solo mostramos los datos mínimos. Si usamos una Rest Api tradicional nos encontraríamos con los siguientes problemas:

Solicitar más información de la que necesitamos: Si usamos el mismo endpoint para ambos casos, en el teléfono traeremos información que no usaremos (ya que no vamos a poder mostrar todo en pantalla), consumiremos datos y batería posicionando nuestra APP en los primeros puestos de consumo de estos preciados recursos (con lo cual, si no somos facebook, nos arriesgamos a que nos desinstalen).

Tener Código duplicado en dos endpoint: Si hacemos dos endpoints (uno para web y otro para teléfono) deberemos mantener ambos funcionando y tendremos problemas si deseamos expandirnos a otras plataformas (tablets o smartTVs). Incluso, si reutilizamos el Código fuente para ambos endpoint, estaríamos obligando a nuestro servidor a calcular toda la información de manera innecesaria.

Resolviendo problemas con consultas en tiempo de ejecución (query API)

Para resolver este problema Facebook creo GraphQL.

GraphQL es un lenguaje de consulta y manipulación de datos para APIs y un entorno de ejecución para realizar consultas con datos existentes. Es decir que permite a los clientes definir la estructura de datos que requiere y el servidor solo procesara los datos requeridos.

El pedido se realiza mediante una “query” (consulta) que se escriben en tiempo de ejecución. Es básicamente un texto plano con una sintaxis propia que se envía a una API para que se ejecute.

// Ejemplo de una query que me traeria informacion para un telefono
// trae unos pocos campos y solo las imagenes para mobile.
{
    UserProfile(email: 'example@gmail.com') {
        name
        lastName
        mobileProfileImage
        haveNotification
        lastPublications {
            mobileImage
            title
        }
    }
}
// Ejemplo de una query que traeria informacion para la web
// trae todos los campos y solo las imagenes para WEB
{
    UserProfile(email: 'example@gmail.com') {
        name
        lastName
        profileDescription
        webProfileImage
        friends {
            webImage
            name
            lastName
            profileUrl
        }
        lastPublications {
            webImage
            title
        }
        photos {
            webImage
            title
        }
        notifications{
            title
            notificationType
        }
    }
}

Principales ventajas

GraphQL no es un reemplazo de REST, es una solución complementaria que viene a resolver otros problemas en los cuales REST no puede ser aprovechado. Son dos herramientas diferentes que solucionan problemas diferentes, es como decidir si utilizar un martillo o una maza.

Por eso decimos que GraphQL…

• Es muy fácil de usar y de aprender. Cuando se logra entender el concepto y como funciona lleva muy poco tiempo escribir un servidor productivo. Implementado correctamente se logra tener bloques de código muy pequeños que son fáciles de leer y corregir.
• Soluciona el overfitting y el underfitting que es el problema de traer demasiados datos o de traer pocos (lo que en REST necesita una nueva llamada a otro servicio).
• Optimiza el uso de la red y los datos ya que permite ejecutar varias querys en el mismo request. Se puede pedir datos de un usuario, stock actual de un producto y los precios segun las diferentes listas con una sola consulta al servidor.
• Puede obtener información de más de un proveedor de datos. Por ejemplo, si una query pide datos usuarios, podemos obtenerlos desde SQL, luego consultar a un Active Directory para conocer los permisos y finalmente buscar la imagen del perfil en una CDN y devolverlo a quien lo pidió.
• El servidor solo procesara la información que se le pide. Si por algún motivo (siguiendo con el ejemplo anterior del usuario) no necesito conocer los permisos que el usuario tiene la consulta al Active Directory no se realizara. Lo mismo sucedería con la CDN si no pido la imagen de perfil.

Componentes básicos

Un servidor GraphQL este compuesto por, al menos, cuatro componentes principales y necesarios.

Servidor

GrapqhQL por si solo no puede funcionar como un servicio web, requiere de algun componente que le se soporte HTTP (como express en NodeJS o ).

• En el ejemplo en Node usaremos: Express y Express-GraphQL
• En el ejemplo en Go usaremos: HTTP (paquete nativo)

Schema

Un schema, en palabras simples, es la lista de querys que nuestro servidor GraphQL va a soportar. Cada elemento dentro del schema corresponde a una opción de datos que el cliente puede pedir.

Un schema esta compuesto de tres elementos:

Type: Es un objeto referencia del tipo de datos que va a devolver (o una lista de ellos). Aquí está el objeto de donde nuestro cliente puede seleccionar que propiedad obtener.

Arguments: Parámetros que se especifican en la query y que se utilizan para filtrar.

Resolvers: La implementación del código necesario para devolver el type que se le asigno.

Types

Los types son los datos que devolvera una query. Estos datos están compuestos de propiedades fuertemente tipadas y perfectamente definidas. Cada propiedad tiene un resolver (responsable de devolver el dato) que puede estar implícito por defecto o customizado por el desarrollador según se necesite.

Es desde aquí donde nuestros clientes tendrá el catálogo de propiedades que puede pedir.

Resolvers

Los resolvers son básicamente el código necesario para devolver el valor que se asignara a una propiedad. Un resolver puede ser implícito, es decir, que se devolverá el dato que tenga el mismo nombre que la propiedad o, puede ser personalizado para tomar un ID de los datos padres y buscar los valores a devolver desde otro origen de datos.

Y sin más preámbulos…

Ya no hay más teoría que conocer con lo cual ya podemos empezar a meter mano en el código.

NodeJS: https://github.com/victorparedes/nodejs-graphql

Go: https://github.com/victorparedes/go-graphql

Les aconsejo comenzar un proyecto desde cero, copiar y pegar el código que dejo de ejemplo para ir entendiendo que hace cada file. Refactoricen, junten todo en un file, sepárenlo de nuevo, escriban test y rompan para entender cómo funciona. También pueden reemplazar el mock de datos que deje y consumir datos desde una base de datos o de otra APIcomo swapi o LOTR.