GraphQL: Qué es y Cómo se Utiliza

GraphQL es un lenguaje de consultas que puedes utilizar con tu API, incluyendo también varios entornos de ejecución que puedes instalar en tu servidor, dependiendo del lenguaje de programación que utilices.

Qué es GraphQL

GraphQL es un novedoso sistema con el que diseñar tus APIs en todos los procesos del mismo, desde el código que hace la llamada a la API del lado del cliente hasta el modo de construirla del lado del servidor.

GraphQL es un lenguaje de consultas desarrollado por Facebook que también incluye diversos entornos de ejecución backend con los que ejecutar tus consultas, según el lenguaje que utilices en tu servidor. Lo mejor de todo es que no es algo que te ate a una tecnología, ya que este sistema puede implementarse con cualquier lenguaje. Del mismo modo que antaño la arquitectura SOAP dominaba el diseño de las APIs, ahora es GraphQL quien compite por convertirse en un estándar y arrebatarle el puesto a la arquitectura REST, que fue la que tomó el relevo de la arquitectura SOAP. Si bien GraphQL se basa en cierto modo en la arquitectura REST, agrega conceptos adicionales que permiten encadenar y enlazar la obtención de recursos del servidor, agregando una nueva dimensión a lo ya conocido.

Además de GraphQL, Facebook también ha desarrollado otras tecnologías como React o React Native. En el caso de GraphQL, se lanzó públicamente en el año 2015, aunque Facebook ya había estado usando esta herramienta durante años.

Los motivos para aprender GraphQL no son pocos, ya que muchas grandes empresas lo utilizan, como Twitter, Pinterest, GitHub, Medium, StackShare o Instagram. Si eres un desarrollador web o tienes intención de serlo, no cabe duda de que es un buen añadido.

Cómo funciona GraphQL

A diferencia de la arquitectura REST, en donde se suelen definir múltiples endpoints en el servidor a los que conectarse, en GraphQL existe un único endpoint al que se envían consultas construidas mediante la sintaxis de consultas de GraphQL. El servidor responderá con los datos que se han pedido en formato JSON.

Un posible ejemplo de una petición GraphQL podría ser el siguiente, en el que obtenemos el nombre del usuario cuyo email es edu@neoguias.com:

GET /graphql?query={ usuario(email: "edu@neoguias.com") { nombre } }

La consulta asociada a esta petición es la siguiente:

{
  usuario(email: "edu@neoguias.com") {
    nombre
  }
}

Cuando el servidor de GraphQL recibe esta consulta, este se encargará de buscar los datos en las tablas o colecciones adecuadas de la base de datos para así proporcionar una respuesta, que en el caso de nuestro ejemplo podría ser la siguiente:

{
  "nombre": "Eduardo"
}

También podrás realizar consultas más complejas. Imagínate que por ejemplo quieres obtener información acerca del trabajo del usuario anterior, y que el trabajo de los usuarios se almacena en la base de datos en un objeto o una tabla llamada empresa que incluye el nombre de la empresa, el lugar de trabajo y el puesto. Lo que vamos a hacer en el siguiente ejemplo es obtener el nombre del usuario indicado y también el puesto que tiene en la empresa en la que trabaja:

GET /graphql?query={ usuario(email: "edu@neoguias.com") { nombre } empresa{ puesto } }

La consulta asociada a esta petición es la siguiente:

{
  usuario(email: "edu@neoguias.com") {
    nombre
    empresa {
      direccion
    }
  }
}

Cuando el servidor de GraphQL reciba y procese la consulta, podría generar, por ejemplo, el siguiente resultado, que sigue la misma estructura del ejemplo anterior y de cualquier otro ejemplo de GraphQL que puedas encontrar:

{
  "nombre": "Eduardo",
  "empresa": {
    "direccion": "Rue del percebe"
  }
}

También puedes hacer referencia a más de un elemento o endpoint mediante una sola consulta:

{
  usuario(email: "edu@neoguias.com") {
    nombre
  }
  notas(id: "4") {
    titulo
  }
}

Consultas GraphQL

A continuación vamos a ver con más detalle cómo puedes crear consultas GraphQL, por lo que veremos los campos y argumentos de las consultas, los alias y también qué son y para qué se utilizan los fragmentos.

Campos y argumentos

Los campos en GraphQL son el nombre de los valores que queremos obtener, ya sean simples o complejos, y los argumentos son los valores de búsqueda de dichos campos.

En el siguiente ejemplo existen dos campos, que son usuario y nombre. También existe un argumento, que es el argumento id, al que le damos el valor de 1:

{
  usuario(id: "1") {
    nombre
  }
}

El campo usuario, representado por su id, debería corresponderse con un objeto que incluye el campo nombre en su interior, que es una cadena. Como ves, los campos no solamente pueden ser valores simples, sino que también pueden ser objetos compuestos por otros campos.

Por otro lado, mediante los argumentos podemos especificar los elementos a los que hacemos referencia. En el ejemplo anterior hemos optado por usar el id del usuario, aunque como ya hemos visto, también podríamos usar otros argumentos, como el nombre del usuario o su email, siempre y cuando la API acepte estos valores.

Los argumentos podrían ser cualquier tipo de campo. Por ejemplo, imagínate que existe el campo documentos, dando por hecho que cada usuario tiene un conjunto de documentos almacenados. Podríamos obtener la lista de documentos haciendo referencia a este campo, pero también podemos hacer uso de otros argumentos que modifiquen la consulta, especificando el número de documentos a obtener.

En el siguiente ejemplo obtenemos el nombre del usuario junto con los primero 10 documentos:

{
  usuario(id: "1") {
    nombre
    documentos(limit: 10)
  }
}

Alias

Los alias permiten obtener un campo con un nombre diferente. Por ejemplo, podríamos obtener un usuario como administrador, y también obtener el campo nombre como nombre_de_pila:

{
  administrador: usuario(id: "1") {
    nombre_de_pila: nombre
  }
}

La consulta anterior, por ejemplo, devolvería los siguientes resultados:

{
  "data": {
    "administrador": {
      "nombre_de_pila": "Eduardo"
    }
  }
}

Esta funcionalidad puede parecer inútil, pero podría ser útil en caso de que quieras evitar procesar el resultado cuando venga de vuelta. Además es el único modo de poder enviar una consulta que haga referencia al mismo endpoint varias veces en la misma consulta:

{
  administrador: usuario(id: "1") {
    nombre_de_pila: nombre
  }
  moderador: usuario(id: "2") {
    nombre_de_pila: nombre
  }
}

Fragmentos

En la siguiente consulta estamos replicando varias veces la estructura de la consulta, ya que hacemos referencia al mismo recursos varias veces:

{
  administrador: usuario(id: "1") {
    nombre_de_pila: nombre
    email
    documentos
  }
  moderador: usuario(id: "2") {
    nombre_de_pila: nombre
    email
    documentos
  }
}

Los fragmentos permiten evitar tener que repetir la misma estructura una y otra vez. Se declaran mediante el término fragment, el nombre del fragmento y una consulta. Por ejemplo, vamos a definir un fragmento para la consulta anterior:

fragment camposUsuario on usuario {
  nombre_de_pila: nombre
  email
  documentos
}

Una vez declarado en fragmento bastará con que hagas referencia a él en la consulta:

{
  administrador: usuario(id: "1") {
    ...camposUsuario
  }
  moderador: usuario(id: "2") {
    ...camposUsuario
  }
}

Variables en GraphQL

GraphQL también incluye la posibilidad de usar variables en las consultas para así poder especificar el valor de los campos de la consulta de forma dinámica.

Por ejemplo, en la siguiente consulta especificamos el id del usuario de forma estática:

{
  administrador: usuario(id: "1") {
    nombre
  }
}

Sin embargo, lógicamente no siempre querremos hacer referencia al valor 1 para el campo id, por lo que se lo tendremos que pasar de algún modo. Seguramente estés pensando en algún tipo de interpolación de variables, al igual que ocurre con los template literals de JavaScript, pero en este caso no podremos seguir esta metodología.

Para definir una variable en la consulta anterior tendremos que simular una función que acepte un id:

query getAdministrador($id: String) {
  administrador: usuario(id: $id) {
    nombre
  }
}

Lo que hemos hecho ha sido darle el nombre getAdministrador a la consulta, tal y como haríamos al crear una función. Resulta bastante útil cuando tienes un gran número de consultas en tu aplicación.

Cuando quieras hacer uso de la consulta anterior tendrás que pasarle las variables. Puedes hacerlo en la propia petición al servidor mediante el parámetro variables, como en el siguiente ejemplo:

GET /graphql?query={ query getAdministrador($id: String) { administrador: usuario(id: $id) { nombre } } }&variables={ "id": "1" }

Si quieres forzar que una variable sea requerida, puedes agregar el caracter ! al final del parámetro:

query getAdministrador($id: String!)

También puedes especificar un valor por defecto para el parámetro:

query getAdministrador($id: String = "1")

Directivas en GraphQL

Las directivas pueden ser usadas en consultas con nombre (funciones) y te permiten establecer condiciones para incluir o excluir ciertos campos de la consulta.

En el siguiente ejemplo pasamos a la consulta la variable obtenerEmpresa, que podrá tener los valores true o false. Si su valor es true vamos a obtener el campo empresa, y a excluirlo en caso de que sea false:

query getAdministrador($id: String, $obtenerEmpresa: Boolean!) {
  usuario(id: $id) {
    nombre,
    empresa: @include(if: $obtenerEmpresa) {
      nombre
      puesto
      direccion
    }
  }
}

Si pasamos a la consulta los siguientes parámetros se obtendrán los datos de la empresa del usuario:

{
  "id": "1",
  "obtenerEmpresa": true
}

Si por el contrario pasamos los siguientes parámetros no se obtendrán:

{
  "id": "1",
  "obtenerEmpresa": false
}

Existen diferentes tipos de directivas. Por un lado tenemos la directiva @include y por otro la directiva @skip.

Directiva @include

La directiva include incluirá el campo indicado siempre que se cumpla la condición especificada:

query getUsuario($id: String, $incluirEmpresa: Boolean) {
  usuario(id: $id) {
    nombre,
    empresa: @include(if: $incluirEmpresa) {
      nombre
      puesto
      direccion
    }
  }
}

{
  "id": "1",
  "incluirEmpresa": true
}

Directiva @skip

La directiva skip excluirá el campo indicado siempre que se cumpla la condición especificada:

query getUsuario($id: String, $excluirEmpresa: Boolean) {
  usuario(id: $id) {
    nombre,
    empresa: @skip(if: $excluirEmpresa) {
      nombre
      puesto
      direccion
    }
  }
}

{
  "id": "1",
  "excluirEmpresa": true
}

Y esto ha sido todo.

---