Introducción a GraphQL

Table of Contents

Introducción

En está ocasión me gustaría hablarles acerca de un tema que me gusta mucho y que he estado usando en los últimos meses, es una tecnología que poco a poco va ganando terreno y que se está convirtiendo en un estándar al momento de diseñar y construir nuestras APIs para aplicaciones modernas, y este tema es GraphQL.

¿Qué es GraphQL?

GraphQL es un estándar que nos permite diseñar nuestras APIs basadas en un esquema y tipos, existen tres principales tipos que conforman un esquema de GraphQL y estos son: Query, Mutation y Subscription (en un post posterior hablaré más acerca de este tema), de los cuáles el único tipo que es obligatorio es Query, veamos la definición de GraphQL extraida de su sitio oficial:

GraphQL es un lenguaje de consulta para APIs y un tiempo de ejecución para resolver esas consultas con sus datos existentes. GraphQL proporciona una descripción completa y comprensible de los datos en su API, le da a los clientes el poder de pedir exactamente lo que necesitan y nada más, facilita la evolución de las API a lo largo del tiempo y habilita poderosas herramientas para desarrolladores.

Hay dos sentencias que rescato de esa definición:

1. Resolver consultas con datos existentes.
2. Le da a los clientes el poder de pedir exactamente lo que necesitan y nada más.

¿Qué son las Query?

Como ves GraphQL se trata de darle al cliente la información exacta que pidió y nada más, todo esto mediante el concepto de Query la cuál podríamos decir que es equivalente a una petición tipo GET en servicios RESTful. La forma de escribir una query es la siguiente:

query {
  posts {
    id
    title
    slug
    body
    author {
      id
      name
    }
  }
}

En este ejemplo estamos haciendo una query al servidor especificándole que queremos todos los posts y específicamente los campos id, title, slug, y body, así como datos relacionados al autor id y name. En este caso las respuesta del servidor sería algo así:

{
  "data": {
    "posts": [
      {
        "id": 1,
        "title": "Introducción a GraphQL",
        "slug": "introduccion-a-graphql",
        "body": "<p>Contenido del post</p>",
        "author": {
          "id": 1,
          "name": "Gustavo Castillo"
        }
      },
      ... // aquí seguiría el listado de posts completo
    ]
  }
}

La respuesta del servidor no es más que un arreglo de objetos en formato JSON donde cada elemento del arreglo representa un post, el cuál podríamos recorrer en el frontend con nuestro framework JS favorito y mostrar los datos en pantalla.

Argumentos

Ahora bien supongamos que únicamente queremos el detalle de un único post y no la lista completa, la pregunta es ¿Cómo hacemos para mandarle parámetros a una query?. Bien veamos como hacer esto:

query {
  singlePost: posts(id: 1) {
    id
    title
    slug
    body
  }
}

En esta ocasión no estoy pidiendo los datos del autor lo cuál es perfectamente válido recuerda GraphQL se trata de pedir exactamente lo que necesitan y nada más, la respuesta está ves sería así:

{
  "data": {
    "singlePost": {
      "id": 1,
      "title": "Introducción a GraphQL",
      "slug": "introduccion-a-graphql",
      "body": "<p>Contenido del post</p>"
    }
  }
}

Si eres algo observador te habrás dado cuenta del prefijo que coloque justo antes de la query posts: singlePost, esto se conoce como alias y suele ser útil cuando queremos “renombrar” algún campo de la query o cuando queremos hacer múltiples queries en una sola petición debido a que no pueden existir dos campos con el mismo nombre la solución es usar un alias distinto a dichos campos.

¿Qué son las Mutation?

Normalmente cuando interactuamos con el servidor no sólo lo hacemos únicamente para leer datos, sino también solemos mandar información para que este la persista en una BD (usualmente), en servicios REST hacemos una petición tipo POST al servidor con la información que queremos almacenar, las Mutation son la forma en la que podemos alterar información en GraphQL. Supongamos que queremos crear un nuevo post en la base de datos, nuestra mutation sería así:

mutation createPost($input: NewPostInput!) {
  createPost(input: $input) {
    id
    title
  }
}

Hay algunos puntos importantes a tomar en cuenta en esta mutation, primero el parámetro $input es la información que será enviada al servidor y es de tipo NewPostInput el símbolo de ! (admiración) significa que este parámetro es obligatorio, la forma de pasar los valores del input a esta query dependerá de la librería que estés usando para consumir la API, por ejemplo, puedes usar Apollo client para consumir tu API.

Al igual que en las queries podemos asignar un alias al valor retornado por la mutación de tal forma que tenga sentido para nuestra aplicación de lado del cliente, así como pedir los datos que queremos obtener después de realizar dicha mutación en este caso el id y el title del post:

mutation createPost($input: NewPostInput!) {
  post: createPost(input: $input) {
    id
    title
  }
}

Conclusión

GraphQL está tomando mucha fuerza y creo que es importante aprender cómo usarlo en nuestros proyectos, al menos te invito a hacer algunas pruebas con el lenguaje de programación que prefieras.

Antes de terminar el post me gustaría decirte que GraphQL no está “matando” a REST de hecho hay algunas personas que están usando las dos opciones al mismo tiempo, sin embargo si tienes la oportunidad de empezar un nuevo proyecto te recomendaría hacerlo pensando en GraphQL desde el principio.