Advertisement
  1. Code
  2. JavaScript
Code

¿Qué Es GraphQL?

by
Difficulty:IntermediateLength:MediumLanguages:

Spanish (Español) translation by Rafael Chavarría (you can also view the original English article)

Vista General

GraphQL es una nueva y emocionante API para consultas ad hoc y manipulación. Es extremadamente flexible y proporciona muchos beneficios. Es particularmente ajustable para exponer datos organizados como gráficos y árboles. Facebook desarrolló GraphQL en 2012 y lo hizo de código abierto en 2015.

Despegó rápidamente y se volvió una de las tecnologías más populares. Muchas compañías innovadoras adoptaron y usaron GraphQL en producción. En este tutorial aprenderás:

  • los principios de GraphQL
  • cómo se compara con REST
  • cómo diseñar esquemas
  • cómo configurar un servidor GraphQL
  • cómo implementar consultas y mutaciones
  • y unos cuántos temas avanzados adicionales

¿En Dónde Brilla GraphQL?

GraphQL está en su mejor punto cuando tus datos son organizados en una jerarquía o una gráfica y el cliente quisiera acceder diferentes subconjuntos de esta jerarquía o gráfica. Considera una aplicación que exponga la NBA. Tienes equipos, jugadores, entrenadores, campeonatos, y mucha información sobre cada uno. Aquí hay algunas consultas de ejemplo:

  • ¿Cuáles son los nombres de los jugadores de la alineación actual de los Golden State Warriors?
  • ¿Cuáles son los nombres, estaturas y edades de los iniciadores de los Washington Wizards?
  • ¿Qué entrenador activo tiene más campeonatos?
  • ¿Para qué equipos y en qué años ganó el entrenador sus campeonatos?
  • ¿Qué jugador ganó más premios MVP?

Podría idear cientos de tales consultas. Imagina que tienes que diseñar una API para exponer todas estas consultas al cliente y poder extender fácilmente la API con nuevos tipos de consultas mientras tus usuarios y gerente de producto idean nuevas y emocionantes cosas para consultar.

Esto no es trivial. GraphQL fue diseñado para abordar este problema exacto, y con un solo punto final de API este proporciona un poder enorme, como verás pronto.

GraphQL vs. REST

Antes de sumergirnos en las tuercas y tornillos de GraphQL, comparémoslo contra REST, que es actualmente el tipo más popular de API web.

REST sigue un modelo orientado a recursos. Si nuestros recursos son jugadores, entrenadores y equipos entonces probablemente habrá puntos finales como:

  • /jugadores
  • /jugadores/<id>
  • /entrenadores
  • /entrenadores/<id>
  • /equipos
  • /equipos/<id>

Frecuentemente los puntos finales sin id solo devuelven una lista de ids, y los puntos finales con el id devuelven la información completa en un solo recurso. Puedes, por supuesto, diseñar tu API de algunas otras maneras (ej. el punto final /jugadores podría devolver también el nombre de cada jugador o toda la información sobre cada jugador).

El problema con esta aproximación en un entorno dinámico es que estas sub-recuperando (ej. obtienes solo los ids y necesitas más información) o estás sobre-recuperando (ej. obteniendo la información completa sobre cada jugador cuando solo estás interesado en el nombre).

Esos son problemas difíciles. Cuando sub-recuperas, si recuperas 100 ids, necesitarás realizar 100 llamadas API por separado para obtener la información sobre cada jugador. Cuando sobre-recuperas, desperdicias mucho tiempo de back-end y ancho de banda de red preparando y transfiriendo muchos datos que no son necesarios.

Hay maneras de abordar esto con REST. Puedes diseñar muchos puntos finales, cada uno devolviendo exactamente la información que necesitas. Esta solución no es escalable. Es difícil mantener consistente la API. Es difícil evolucionarla. Es difícil documentarla y usarla. Es difícil mantenerla cuando hay mucho empalme entre esos puntos finales.

Considera estos puntos finales adicionales:

  • /jugadores/nombres
  • /jugadores/nombres_y_campeonatos
  • /equipos/titulares

Otra aproximación es mantener un número pequeño de puntos finales genéricos, pero proporcionar muchos parámetros de consulta. Esta solución evita el problema de muchos puntos finales, pero va en contra del grano del modelo REST, y también es difícil evolucionar y mantener consistentemente.

Podrías decir que GraphQL ha llevado esta aproximación al límite. No piensa en términos de recursos bien-definidos, pero en su lugar en términos de sub-gráficas del dominio entero.

El Sistema Tipo GraphQL

GraphQL modela el dominio usando un sistema tipo que consiste en tipos y atributos. Cada atributo tiene un tipo. El tipo de atributo puede ser uno de los tipos básicos que GraphQL proporciona como ID, String, y Booleano, o tipo definido por el usuario. Los nodos de la gráfica son tipos definidos por el usuario, y los bordes son los atributos que tienen tipos definidos por el usuario.

Por ejemplo, si un tipo "Jugador" tiene un atributo "equipo" con el tipo "Equipo" entonces significa que hay un borde entre cada nodo de jugador a un nodo de equipo. Todos los tipos son definidos en un esquema que describe el objeto de modelo dominio GraphQL.

Aquí hay un esquema muy simplificado para el dominio NBA. El jugador tiene un nombre, un equipo con el que está más asociado (sí, sé que los jugadores algunas veces se mueven de un equipo a otro), y el número de campeonatos que ganó el jugador.

El equipo tiene un nombre, un arreglo de jugadores, y el número de campeonatos que el equipo ganó.

También hay puntos de entrada predefinidos. Esos son Consulta, Mutación y Suscripción. El cliente se comunica con el servidor a través de los puntos de entrada y los personaliza para sus necesidades.

Aquí está una consulta que simplemente devuelve todos los jugadores:

El punto de exclamación significa que el valor no puede ser nulo. En el caso de la consulta allPlayers, puede devolver una lista vacía, pero no nula. También, significa que no puede haber un jugador nulo en la lista (porque contiene Player!).

Configurando un Servidor GraphQL

Aquí está un servidor completo GraphQL basado en node.-express. Tiene almacén de datos codificado en memoria. Normalmente, los datos estarán en una base de datos o serán recuperados de otro servicio. Los datos son definidos aquí (disculpas por adelantado si tu equipo favorito no aparece):

Las librerías que uso son:

Este es el código para construir el esquema. Nota que agregué un par de variables a la consulta raíz allPlayers.

Aquí viene la parte clave: enganchar las consultas y de hecho servir los datos. El objeto rootValue podría contener múltiples raíces.

Aquí, solo está el allPlayers. Este extrae el offset y límite de los argumentos, corta los datos de todos los jugadores, y después establece el equipo sobre cada jugador basado en el id del equipo. Esto hace a cada jugador un objeto anidado.

Finalmente, aquí está el punto final graphql, pasando el esquema y el objeto de valor raíz:

Establecer graphql a true nos permite probar el servidor con un increíble IDE GraphQL en el navegador. Lo recomiendo altamente para experimentar con diferentes consultas.

Consultas Ad Hoc Con GraphQL

Todo está establecido. Naveguemos a http://localhost:3000/graphql y divirtámonos.

Podemos iniciar de manera sencilla, con solo una lista de los nombres de los jugadores:

Muy bien. Tenemos algunas super estrellas aquí. Sin duda. Vayamos por algo más elegante: comenzando desde offset 4 obtiene 2 jugadores. Por cada jugador, devuelve su nombre y cuántos campeonatos han ganado así como el nombre de su equipo y cuántos campeonatos ha ganado el equipo.

Así que Kobe Bryant ganó cinco campeonatos con los Lakers, quienes ganaron 16 campeonatos en total. Kevin Durant ganó solo un campeonato con los Warriors, quienes ganaron cinco campeonatos en total.

Mutaciones GraphQL

Magic Johnson era un mago en la cancha por supuesto. Pero no lo habría podido hacer sin su amigo Kareem Abdul-Jabbar. agreguemos a Kareem a nuestra base de datos. Podemos definir mutaciones GraphQL para realizar operaciones como agregar, actualizar y remover datos de nuestra gráfica.

Primero, agreguemos un tipo de mutación al esquema. Luce un poco como una firma de función:

Después, necesitamos implementarla y agregarla al valor raíz. La implementación simplemente toma los parámetros proporcionados por la consulta y agrega un nuevo objeto al data['allPlayers']. También asegura establecer el equipo correctamente. Finalmente, devuelve el nuevo jugador.

Para agregar de hecho a Kareem, podemos invocar la mutación y consultar al jugador devuelto:

Aquí hay un pequeño secreto sobre mutaciones... son de hecho exactamente lo mismo que las consultas. Puedes modificar tus datos en una consulta y podrías solo devolver datos desde una mutación. GraphQL no va a fisgonear en tu código. Ambas consultas y mutaciones pueden tomar argumentos y devolver datos. Es más como azúcar sintética para hacer tu esquema más legible por humanos.

Temas Avanzados

Suscripciones

Las suscripciones son otra característica genial de GraphQL. Con suscripciones, el cliente puede suscribirse a eventos que serán disparados siempre que el estado del servidor cambie. Las suscripciones fueron introducidas en una etapa posterior y son implementadas por distintos marcos de trabajo en diferentes maneras.

Validación

GraphQL verificará cada consulta o mutación contra el esquema. Esta es una gran victoria cuando los datos de entrada tienen una forma compleja. No tienes que escribir código de validación molesto y frágil. GraphQL se encargará de eso por ti.

Instrospección de Esquema

Puedes inspeccionar y consultar el esquema mismo. Eso te da poderes meta para descubrir dinámicamente el esquema. Aquí está una consulta que devuelve todos los nombres tipo y su descripción:

Conclusión

GraphQL es una emocionante tecnología API nueva que proporciona muchos beneficios sobre APIs REST. Hay una vibrante comunidad detrás de el, sin mencionar Facebook. Predigo que se volverá un estandarte front-end en poco tiempo. Pruébalo. Te gustará.

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.