GraphQL: la al­te­r­na­ti­va flexible a REST para programar API

Las apli­ca­cio­nes web utilizan API, en inglés Ap­pli­ca­tion Pro­gra­m­mi­ng In­te­r­fa­ces o in­te­r­fa­ces de pro­gra­ma­ción de apli­ca­cio­nes en ca­s­te­llano, para el in­te­r­ca­m­bio y tra­ta­mie­n­to de datos, de modo que, si otros servicios han de acceder a datos de tu proyecto web, debes de­sa­rro­llar e im­ple­me­n­tar una interfaz de este tipo. También aquí existen es­tá­n­da­res asentados como SOAP o REST (Re­pre­se­n­ta­tio­nal State Transfer), que fijan una es­tru­c­tu­ra elemental para tu API co­m­pa­ti­ble con cualquier lenguaje usual de pro­gra­ma­ción –la segunda ar­qui­te­c­tu­ra en especial se ha co­n­ve­r­ti­do en los últimos años en una solución excelente debido a su si­m­pli­ci­dad.

Pero, aunque el triunfo de la ar­qui­te­c­tu­ra de REST im­pre­sio­na, existen al­te­r­na­ti­vas, como GraphQL, igua­l­me­n­te co­n­vi­n­ce­n­tes. El lenguaje de consulta y entorno de tiempo de ejecución de la casa Facebook puede competir pe­r­fe­c­ta­me­n­te con SOAP y REST, si bien sus fa­cu­l­ta­des saltan a la luz en las consultas de mayor co­m­ple­ji­dad.

GraphQL es un lenguaje de consulta similar a SQL de­sa­rro­lla­do por Facebook en 2012, que incluye un entorno de tiempo de ejecución y un sistema de tipos. Ori­gi­na­l­me­n­te estaba destinado ex­clu­si­va­me­n­te a su apli­ca­ción interna. La causa fue la re­mo­de­la­ción de las apli­ca­cio­nes móviles nativas de Facebook para iOS y Android, las cuales mostraban un re­n­di­mie­n­to cada vez más bajo debido a un aumento de la co­m­ple­ji­dad. En especial para la entrega de los datos del hilo de noticias, la mu­l­ti­na­cio­nal debía encontrar una solución que re­pre­se­n­ta­ra una relación sa­ti­s­fa­c­to­ria entre la in­fo­r­ma­ción que se so­li­ci­ta­ba y las consultas al servidor. En 2015, Facebook li­be­ra­li­zó el acceso al código fuente de GraphQL, que en aquel momento ge­s­tio­na­ba casi en solitario el acceso a los datos de las apli­ca­cio­nes móviles. Desde 2017, el proyecto se de­sa­rro­lla bajo la licencia gratuita OWFa-1.0 (Open Web Fou­n­da­tion).

Para entender el fu­n­cio­na­mie­n­to de GraphQL, es necesario explicar los tres co­m­po­ne­n­tes ele­me­n­ta­les que ca­ra­c­te­ri­zan al proyecto de código abierto:

• Lenguaje de consulta: en primer lugar, el concepto GraphQL describe un lenguaje de consulta (Query Language) que facilita a los programas el acceso a una API. Mientras otras ar­qui­te­c­tu­ras de interfaz solo permiten consultas estrictas que a menudo solo ga­ra­n­ti­zan acceder a un solo recurso, las consultas GraphQL se di­s­ti­n­guen por una gran fle­xi­bi­li­dad. Esta se demuestra, en concreto, por el hecho de no existir un límite para el número de recursos co­n­su­l­ta­dos y porque se pueden definir exac­ta­me­n­te los campos de datos que se van a consultar. GraphQL permite tanto consultas de lectura como de escritura.
• Sistema de tipos: GraphQL trabaja con un sistema propio de tipos que permite describir a una API con tipos de datos. Las es­tru­c­tu­ras de datos definidas de este modo son las que crean el marco para las consultas. Cada tipo consta de uno o varios campos que, a su vez, contienen sus propios tipos de datos. Este sistema in­di­vi­dual sirve a GraphQL como punto de orie­n­ta­ción para validar consultas y poder rechazar las erróneas.
• Entorno de tiempo de ejecución: por último, GraphQL también ofrece distintos entornos de tiempo de ejecución para se­r­vi­do­res para llevar a cabo consultas GraphQL. Este es el propósito de las bi­blio­te­cas di­s­po­ni­bles para distintos lenguajes de pro­gra­ma­ción, por ejemplo, Go, Java, Ja­va­S­cri­pt, PHP, Python o Ruby, que otorgan una gran libertad al usuario a la hora de elegir el lenguaje de su API GraphQL. No obstante, el entorno de tiempo de ejecución es ex­clu­si­va­me­n­te re­s­po­n­sa­ble de la co­n­ve­r­sión (análisis) y va­li­da­ción de las consultas, además de la se­ria­li­za­ción de las re­s­pue­s­tas (co­n­ve­r­sión del objeto en un orden co­rre­s­po­n­die­n­te de bits). Guardar y calcular los datos (por ejemplo, en un banco de datos) co­rre­s­po­n­de al ámbito de funciones de tu apli­ca­ción web.

La in­ter­ac­ción del lenguaje de consulta, el sistema de tipos y el entorno de tiempo de ejecución genera una es­tru­c­tu­ra API ex­tre­ma­da­me­n­te versátil no solo para cualquier pla­ta­fo­r­ma o apli­ca­ción, sino que también puede ajustarse pe­r­fe­c­ta­me­n­te a las pro­pie­da­des de tu apli­ca­ción web: puedes integrar la interfaz de GraphQL sin problemas en el código de tu proyecto, in­de­pe­n­die­n­te­me­n­te del marco de trabajo que utilices, sea Django, Rails o Node.js.

Una de las ca­ra­c­te­rí­s­ti­cas pri­n­ci­pa­les de GraphQL es la sencillez del lenguaje de consulta, que facilita a los de­sa­rro­lla­do­res el acceso a la interfaz. Al utilizar GraphQL es fácil darse cuenta de que las re­s­pue­s­tas que se obtienen reflejan exac­ta­me­n­te las consultas que se han formulado. El formato de salida es el ligero y popular formato Ja­va­S­cri­pt JSON (Ja­va­S­cri­pt Object Notation). Por lo tanto, enviar una consulta exacta no debería suponer ningún desafío, siempre que conozcas la es­tru­c­tu­ra de los datos que tu apli­ca­ción necesita y la formules en la consulta. Junto a la sencillez en la creación de consultas, GraphQL destaca es­pe­cia­l­me­n­te por las si­guie­n­tes ca­ra­c­te­rí­s­ti­cas:

• Es­tru­c­tu­ra je­rá­r­qui­ca: las bases de datos que pueden co­n­su­l­tar­se con API de GraphQL tienen una es­tru­c­tu­ra je­rá­r­qui­ca. Es posible generar re­la­cio­nes de forma au­to­má­ti­ca entre los objetos que permiten formular (y responder) consultas complejas en una única solicitud. El in­te­r­ca­m­bio de mensajes entre el servidor y el cliente (también llamados “round trips”) no es necesario. Esta jerarquía de datos es es­pe­cia­l­me­n­te idónea para bases de datos orie­n­ta­das a grafos como Ja­nu­s­Gra­ph y para in­te­r­fa­ces de usuario que también suelen ordenarse je­rá­r­qui­ca­me­n­te.
• Ti­pi­fi­ca­ción estricta: cada nivel en una consulta GraphQL co­rre­s­po­n­de a un de­te­r­mi­na­do tipo, y cada tipo describe un conjunto de campos di­s­po­ni­bles. No obstante, este sistema de tipos no solo puede de­te­r­mi­nar au­to­má­ti­ca­me­n­te si una consulta está formulada de manera correcta o in­co­rre­c­ta: como SQL y gracias a la estricta ti­pi­fi­ca­ción, GraphQL puede emitir mensajes de error ya durante el de­sa­rro­llo o el envío de consultas.
• Fle­xi­bi­li­dad: GraphQL permite formular consultas flexibles y otorga al usuario una gama de li­be­r­ta­des y ventajas en el de­sa­rro­llo y ajuste de tu interfaz. No­r­ma­l­me­n­te se requieren pocos reajustes del lado del servidor, aunque el equipo de de­sa­rro­lla­do­res puede actuar de manera to­ta­l­me­n­te in­de­pe­n­die­n­te respecto del equipo re­s­po­n­sa­ble del co­m­po­ne­n­te cliente. Además, todos los cambios o las am­plia­cio­nes de las API se pueden ejecutar sin ve­r­sio­na­do, ya que, si es necesario añadir campos adi­cio­na­les, se puede hacer fá­ci­l­me­n­te sin pe­r­ju­di­car a los clientes exi­s­te­n­tes.

Ya hemos me­n­cio­na­do el gran éxito de REST en la World Wide Web de la misma forma que hemos hecho hincapié en GraphQL como una al­te­r­na­ti­va seria a esta co­n­so­li­da­da ar­qui­te­c­tu­ra para servicios web, basada en HTTP y orientada a recursos. Lo que lo hizo posible fue, sobre todo, un de­sa­rro­llo que fue el que motivó a Facebook a la co­n­ce­p­ción de GraphQL: la creciente re­le­va­n­cia y co­m­ple­ji­dad de las apli­ca­cio­nes web móviles. Es en especial en las apli­ca­cio­nes de Android, iOS, etc., donde se demuestra la gran fortaleza de GraphQL como base para API: con una única consulta se puede acceder a todos los datos.

La instancia servidor de GraphQL entrega exac­ta­me­n­te la in­fo­r­ma­ción definida en la consulta, de manera que no se envíen ni más ni menos datos de los ne­ce­sa­rios a través de la interfaz. En otras API REST co­m­pa­ra­bles puedes consultar solamente un registro por consulta, con lo cual este se emite en su totalidad. Si hacemos una co­m­pa­ra­ción directa entre GraphQL y REST, se demuestra que el concepto de consulta de Facebook es co­n­si­de­ra­ble­me­n­te más preciso y eficaz, lo cual beneficia al re­n­di­mie­n­to de tu apli­ca­ción. Este vale la pena es­pe­cia­l­me­n­te para usuarios de di­s­po­si­ti­vos móviles, cuya conexión a internet es fre­cue­n­te­me­n­te débil.

Mientras que, por un lado, la libertad de las consultas en GraphQL genera muchas ventajas, por el otro puede conllevar, sin embargo, serios problemas de seguridad, sobre todo, si quieres ofrecer API abiertas a través de las cuales no puedes controlar el co­m­po­r­ta­mie­n­to de las consultas de clientes de terceros. Podría ocurrir que una gran cantidad de consultas provocara un fallo o caída del servidor (de forma in­te­n­cio­na­da o in­i­n­te­n­cio­na­da). Esta situación, de la que debes pro­te­ge­r­te de­bi­da­me­n­te, no es tan inminente si im­ple­me­n­tas una API REST. Im­ple­me­n­tar GraphQL en el backend de tal forma que rinda y funcione de manera segura es bastante más difícil.

Además, la im­ple­me­n­ta­ción de un método de al­ma­ce­na­mie­n­to en caché es mucho más co­m­pli­ca­do para las consultas in­va­ria­bles de GraphQL que para consultas a través de una interfaz REST. Estas se pueden guardar te­m­po­ra­l­me­n­te (por ejemplo, en el navegador) con los métodos de al­ma­ce­na­mie­n­to en caché de la es­pe­ci­fi­ca­ción HTTP.

GraphQL te ofrece, gracias a la amplia oferta de bi­blio­te­cas di­s­po­ni­bles, múltiples opciones a la hora de escoger el lenguaje de pro­gra­ma­ción base. Esta es también una de las mayores ventajas a la hora de im­ple­me­n­tar una interfaz de GraphQL en tu apli­ca­ción. De esta manera, si te gusta Phyton, puedes recurrir a la bi­blio­te­ca Graphene o trabajar con la bi­blio­te­ca GraphQL-java si tu proyecto se basa en Java. Si tu apli­ca­ción web se basa en el entorno de tiempo de ejecución de Ja­va­S­cri­pt Node.js, GraphQL.js puede servir, entre otros, como base para su im­ple­me­n­ta­ción.

En el siguiente tutorial de GraphQL te ex­pli­ca­mos cómo empezar a utilizar el framework API para una apli­ca­ción Ja­va­S­cri­pt, donde, además de la me­n­cio­na­da bi­blio­te­ca GraphQL.js, también se emplea el marco web Express.

Para poder utilizar bi­blio­te­cas GraphQL, debes in­s­ta­lar­las primero. Para instalar la bi­blio­te­ca Ja­va­S­cri­pt GraphQL.js utiliza el gestor de paquetes de Ja­va­S­cri­pt npm (Node Package Manager) y el siguiente comando:

Como al­te­r­na­ti­va, puedes adquirir la bi­blio­te­ca también desde el gestor de paquetes y de­pe­n­de­n­cias Yarn de­sa­rro­lla­do, entre otros, por Facebook (pri­n­ci­pa­l­me­n­te) y Google:

En cualquier caso, es necesario tener instalada una versión actual de Node.js (re­co­me­n­da­mos Node v6.0.0 o superior).

Para que tu apli­ca­ción pueda procesar consultas GraphQL, necesitas un esquema que defina el tipo “Query” (es decir, “consulta”) y el punto de acceso a tu interfaz (también llamado raíz API) que incluye la función “resolver”. Para realizar una interfaz GraphQL que úni­ca­me­n­te emita el mensaje “¡Hola, mundo!”, el código que se es­cri­bi­ría en el archivo server.js creado para este fin sería este:

Si ejecutas este código con Node.js in­tro­du­cie­n­do en la terminal este comando:

deberías obtener este mensaje de respuesta:

Tras haber generado una consulta sencilla en los pasos an­te­rio­res y haberla ejecutado en la terminal de comandos, es el momento de poner en marcha un servidor API GraphQL. Con él podrás, por ejemplo, acceder a la interfaz uti­li­za­n­do un navegador web corriente. Para ello, instala primero el framework de apli­ca­cio­nes Express pre­via­me­n­te me­n­cio­na­da, así como la bi­blio­te­ca express-GraphQL con este comando:

A co­n­ti­nua­ción, modifica la consulta GraphQL “¡Hola, mundo!” de tal modo que, en lugar de un sencillo script, se convierta en la base de tu servidor GraphQL. Para ello, im­ple­me­n­ta el módulo Express y utiliza la bi­blio­te­ca express-GraphQL para integrar el servidor API con el punto final HTTP “/graphql”:

Como en el ejemplo anterior, abre el archivo server.js con Node.js, con la di­fe­re­n­cia de que esta vez no ejecutas una consulta, sino que inicias tu servidor API:

En el código del servidor Express GraphQL no solo se es­pe­ci­fi­ca el esquema y la raíz API, sino que también se genera el punto final HTTP “/graphql”. Mediante la entrada “graphiql: true” se activa, entre otros, la he­rra­mie­n­ta homónima que te facilita la entrada de consultas a través de una interfaz gráfica de usuario. Para ello, abre tu navegador e introduce la siguiente dirección:

Una vez in­s­ta­la­dos los co­m­po­ne­n­tes ne­ce­sa­rios me­n­cio­na­dos, creado tu primer esquema de consulta y puesto en marcha tu propio servidor, tal como se describe en los pasos de este tutorial para GraphQL, estás preparado para fa­mi­lia­ri­zar­te con las po­si­bi­li­da­des de entrada de consultas.

Puedes encontrar más in­fo­r­ma­ción al respecto, así como ex­pli­ca­cio­nes de­ta­lla­das sobre el diseño de backends y frontends de GraphQL en la sección de tu­to­ria­les de la página oficial de de­sa­rro­llo de la API de Facebook.