Implementando una API con GraphQL (Parte 1)
Estaba ansioso por escribir sobre GraphQL en SaasRadar.
Debo confesar que esta tecnología me enamoró desde que comencé a estudiarla y vi sus potencialidades.
Mi objetivo hoy es que, si aún no conoces GraphQL, al terminar el artículo salgas con una idea general de su funcionamiento, veas una implementación sencilla y puedas ir directo a conocer todos los detalles en su documentación oficial.
Luego de eso, a sacarle partido, no es nada complicado.
Entonces, ¿comenzamos?
¿Qué es una API?
API, abreviatura de Application Programming Interface, es un conjunto de técnicas, funciones y procedimientos que facilitan la integración entre servicios al exponer los datos de un sistema mediante uno o varias direcciones URL.
Estas pueden ser consultadas desde cualquier software de terceros con independencia de su lenguaje de programación y arquitectura.
Como ejemplos de API más populares tenemos la autenticación de Google o Facebook en cualquier sitio web o aplicación.
A estos servicios se le pasan las credenciales del usuario a la URL que tienen definida para este fin. Ellos buscan en sus bases de datos si esas credenciales son correctas y devuelven el resultado.
Otros ejemplos de API que usamos a diario son las pasarelas de pago, cuando pagamos desde un sitio determinado mediante la integración de los servicios.
Para entender el presente debemos partir del pasado, entonces deberíamos preguntarnos:
¿Cómo era el desarrollo de API antes de GraphQL?
Para no hacer la historia larga, antes de GraphQL tuvimos primeramente SOAP y luego a REST.
De REST hemos hablado mucho en SaasRadar, es una forma de crear API que utiliza las peticiones HTTP clásicas GET, POST, PUT y DELETE para realizar operaciones sobre un punto de entrada que en la práctica es una dirección URL.
REST es una muy buena opción para implementar API e integrar servicios, pero tiene algunas limitantes.
¿Qué limitantes tiene REST?
La primera es que una aplicación necesita varios puntos de entrada, cantidad que aumenta de una forma directamente proporcional a su complejidad.
Esto se traduce en que, para desarrollar un cliente, debes tener en cuenta todos estos puntos de entrada con sus parámetros y formato de retornos.
O sea, para una aplicación fácilmente podrías tener 10 URL diferentes colocadas en el código para hacerle peticiones en dependencia de lo que quisieras obtener.
Haciendo una analogía, imagina que tienes un supermercado, y decides separar cada producto en un punto de venta diferente dentro del mismo supermercado.
Contratas un trabajador por cada punto de venta y cuando llegan los clientes deben dirigirse al punto de venta del producto que desean para hacer el pedido. Si quiere 20 productos, debe dirigirse a 20 lugares.
La segunda limitante es que cada punto de entrada se programa de forma genérica para devolver todos los datos que pudiera necesitar cualquier cliente. Al no saber que dato podrá querer, se los envío todos y que él escoja.
Es funcional, pero el consumo de datos aumenta por el envío de esta información innecesaria.
👉. También te puede interesar: API REST: Cómo consumir servicios en diferentes lenguajes
¿Qué es GraphQL, y como soluciona estas limitantes?
GraphQL es un lenguaje de consulta y manipulación de API desarrollado por Facebook y lanzado públicamente en el año 2015.
Sus principales ventajas son, precisamente, que la API tendrá un solo punto de entrada (URL) y que el cliente es quien define qué información desea conocer mediante un lenguaje de consultas con una estructura establecida.
Como tercera ventaja tenemos que no es necesario documentar la API una vez terminada.
¡Qué trabajo tan tedioso esa documentación!
Pues nada, GraphQL te la va generando a medida que la programas.
Llevándolo a la analogía de antes, dejaste en el supermercado un único punto de venta con todos los trabajadores y las capacidades para atender a todos los clientes, de modo que pueden solicitar cualquier producto y se le brindará solamente la información que pida.
Al tener un solo punto de entrada el sistema permite a los desarrolladores una mayor integración con esta tecnología.
El punto de entrada puede especificarse por configuración y todas las peticiones se harán utilizando una única variable.
La otra ventaja es más obvia, ¿quién necesita que las respuestas enviadas por el servidor tengan datos innecesarios que provoquen un mayor consumo de ancho de banda y, por tanto, menor rendimiento?
Si ya quedaron claras las ventajas, veamos una sintaxis de consulta con GraphQL.
{
articulo (id: "9") {
titulo,
autor {
nombre
}
}
}
De este modo estaríamos solicitando desde la aplicación cliente el título y el nombre del autor del artículo con id 9. A esta consulta el servidor debe responde de este modo:
{
"data": {
"articulo": {
"titulo": "Implementando una API basada en GraphQL",
"autor": {
"nombre": “Yasmani”
}
}
}
}
Vamos a implementar este ejemplo a continuación. Para esto podemos elegir prácticamente cualquier lenguaje de programación, a estas alturas ya ha implementaciones de GraphQL para la mayoría.
Hoy vamos a elegir Django para el lado del servidor, uno de los mejores framework para backend y el más completo entre los basados en Python en mi opinión.
Preparando el entorno
El primer paso es descargar Python, puedes hacerlo desde aquí. En este proceso debes asegurarte de marca la casilla que permite incluir Python y pip en las variables de entorno.
Una vez instalado Python procedemos a instalar Django a través de pip de este modo:
python -m pip install Django
Para crear el proyecto con Django ejecutaremos el comando:
django-admin startproject saasradar_server
Y dentro del proyecto crearemos nuestra aplicación:
python manage.py startapp blog
Para incorporar GraphQL a Django vamos a instalar mediante pip el paquete Graphene.
pip install graphene-django
Ahora agregamos Graphene y nuestra app blog a las aplicaciones instaladas de Django a través de su archivo de configuración settings.py.
Y configuramos la URL a la que responderá GraphQL.
Ahora corresponde definir donde pondremos el esquema GraphQL del proyecto en el fichero settings.py
Según esta configuración, en la raíz del proyecto debemos crear un archivo llamado schema.py que debe quedar así:
De este modo ya todo el ambiente de trabajo está listo, ¿lo probamos?
Sitúate en la raíz del proyecto en tu consola y ejecuta:
python manage.py runserver
Podrás ver como se despliega tu aplicación en un servidor de pruebas al cual puedes acceder entrando en tu navegador web favorito a la URL http://localhost:8000/graphql. Debes obtener la interfaz de GraphQL sobre la que posteriormente haremos pruebas.
Todo listo, ¡a programar!
Creamos las entidades que representarán a nuestra base de datos.
En este caso muy simplificado tendremos 3 clases, Autor, Categoría y Artículo con sus atributos específicos y sus relaciones a través de las llaves foráneas.
Vamos a llevar este modelo a la base de datos. Para esto debemos ejecutar los comandos:
python manage.py makemigrations python manage.py migrate
Nos toca ahora el plato fuerte, implementar como responderá la aplicación a los diferentes pedidos. Esto se define en el fichero schema.py que creamos anteriormente.
Empezaremos definiendo una Query que nos devuelva todos los Autores. Para esto agregamos el siguiente código a nuestro archivo schema.py.
Donde definimos el Tipo del Autor, indicando a que modelo representa y cuales son los campos que haremos visibles a través de la API.
Posteriormente definimos nuestra Query donde especificamos el nombre como todos_autores y el método para resolverlo que simplemente hace una consulta a la base de datos devolviendo todos los objetos de tipo autor.
Si lo probamos desde nuestra interfaz de GraphQL:
Ahora vamos a definir otra consulta un poco más complicada. En esta ocasión queremos todos los artículos de un determinado autor, y lo resolveremos agregando el siguiente código.
Donde definimos los Tipos Artículo y Categoría, especificamos que el nombre de la consulta es articulos_por_autor, que requiere el id del autor, incluimos en la consulta toda la información del autor y la categoría y filtramos por el id del autor. Vamos a probarlo.
Pero me doy cuenta que no necesito todos estos datos, solo quiero obtener el título, el usuario y el nombre del autor, ¿tengo que cambiar algo en el código?
Pues no, como decíamos anteriormente, es una de las grandes ventajas de GraphQL, solamente le pedimos los datos que queremos y ahí está nuestra API para darnos justo esa información. Vamos allá.
Hasta este punto dejamos en funcionamiento una API sencilla a modo de ejemplo de las potencialidades de GraphQL.
Posteriormente debes implementar la interfaz de usuario con un cliente GraphQL que se conecte a esta API y consuma los servicios que acabamos de desarrollar.
Si no sabes que tecnología elegir para esta tarea te recomiendo nuestro artículo sobre los mejores frameworks frontend.
Por hoy me despido, espero que te sea útil esta información y que podamos seguir hablando de GraphQL en el futuro. Les dejo todo el código de este ejemplo aquí.
No olvides visitar la web oficial de GraphQL para que analices todas las facilidades que brinda.
Web Oficial: https://graphql.org/
📚 Artículo siguiente de esta serie: Implementando una API con GraphQL (Parte 2)
