Introducción práctica a GraphQL I

La semana pasada en la conferencia de ReactJS Europa, Facebook presentó GraphQL, esta vez con más detalle que en la conferencia de EE.UU. GraphQL es una nueva especificación que modela queries a un servidor. Se trata de usar una serie de objetos, que recuerdan mucho a una cadena JSON, para modelar los datos exactos que necesitas.

Algunos ejemplos serían los siguientes:

type User {  
  id: String!
  name: String
}

type AdminGroup {  
  gid: String!
  users: [USer]
}

type Query {  
    user(id: String!): User
    adminGroup(gid: String!): AdminGroup
}

Está claro que, aun sin ser exactamente JSON, se parece bastante. Además, como se puede ver en el ejemplo, TODO es un "objeto", como lo podemos entender los programadores de Javascript. El conjunto de definiciones del ejemplo forman el esquema de nuestro sistema y, sobre ese esquema, podemos construir consultas de la siguiente forma:

adminGroup(gid: 1){  
    gid
    users {
        name
    }
}

La query escrita así es muy fácil de leer: pedimos el Admingroup con id=1. De él nos interesa su gid, y de los usuarios que están en la lista user, únicamente necesitamos saber el nombre. Así, una respuesta válida del servidor sería más o menos como sigue:

{
    data: {
        adminGroup: {
            gid: 1,
            users: [
                {
                    name: 'Carlos'
                },
                {
                    name: 'Pepe'
                }
            ]
        }
    }
}

Esta es una respuesta perfectamente válida para consumir en nuestros clientes. Pero lo mejor es que no hemos tenido que preocuparnos, desde el lado del cliente, de los detalles de implementación o de la estructura de datos para obtener la información que queríamos. Esto sería imposible, por ejemplo, si estuviéramos atacando una API Rest.

Vamos a ver unos cuentos ejemplos más concretos, para poder entender mejor de qué se trata todo esto de GraphQL.

Usaremos la implementación en JS que han hecho en Facebook, que no es más que una implementación de la especificación de GraphQL que podrías replicar en cualquier lenguaje.

Hello World:

La consulta más básica que podemos hacer es aquella que pide por un dato hardcoding:

import {  
  graphql,
  GraphQLSchema,
  GraphQLObjectType,
  GraphQLString
} from 'graphql';


var schema = new GraphQLSchema({  
  query: new GraphQLObjectType({
    name: 'RootQueryType',
    fields: {
      hello: {
        type: GraphQLString,
        resolve: () => 'world'
      }
    }
  })
});

var query = '{ hello }';

graphql(schema, query).then(result => {

  // Prints
  // {
  //   data: { hello: "world" }
  // }
  console.log(JSON.stringify(result));

});

Vamos a ir paso a paso:

  • Primero se importa una serie de clases y una función graphql.

  • Luego hay que definir un esquema; es decir, una clase que aglutina todas las queries que puede haber en el sistema. En este caso solo hay una posible query {hello} cuyo valor ha de ser un String y, además, está "hardcodeado" al string world.

  • El seguiente paso es crear la query. Puedes pensar en las queries como en objetos JSON, pero sin valores, solo claves, ya que es GraphQL quien se encarga de completarlos. Para completar una clave siempre usa la función resolver.

  • Por último, hay que pasarle a la función graphql nuestro esquema y nuestra query. En el ejemplo hemos especificado que, cuando en un query venga una clave hello, debe asignársele el valor world. Nuestra función (que devuelve una promesa), se resuelve con el objeto {hello:'world'}.

No te líes con tanto new y tanta clase. En resumidas cuentas, se trata simplemente de decirle a GraphQL que, cuando en la consulta venga tal key, devuelve tal value.

No te pierdas la segunda parte de esta serie donde veras la forma de hacer convivir GraphQL junto a una API Rest.

Si te ha gustado este post, difunde la palabra. Tampoco dudes en dejar comentarios u observaciones. ¡Gracias! :)

Suscríbete a mi lista de correo

* Campos obligatorios