GraphQL: La nueva (y mejorada) forma de construir API’s

En la última conferencia de desarrolladores de GitHub, la empresa hizo un gran anuncio: Su nueva API GraphQL, la cual ha sido publicada para su acceso a través del programa de acceso temprano. En este post, hago un esfuerzo por explicar qué es GraphQL y por qué es importante para la comunidad.

"Un lenguaje de consultas para tus API's"
«Un lenguaje de consultas para tus API’s»

Primero, un poco de historia.

GraphQL fue creado en Facebook y liberado como un proyecto Open-Source, de igual manera que React.js. La idea original era permitir que los clientes de los servicios Rest pudieran decidir qué información le interesa en un particular end-point.  Quienes han trabajado desarrollando servicios REST, sabrán que muchas veces la cantidad de información que termina devolviendo un end-point particular es enorme, y no todos los casos de uso la consumen en su totalidad.

¿Por qué importa?

¿Por qué si los servicios REST de GitHub son tan alabados en la industria, ahora se mudan a GraphQL?. Por la misma razón que otros gigantes de la industria han comenzado a adoptarlo. Los detalles están en su anuncio, pero el resumen es el siguiente:

  • REST requiere varias consultas, GraphQL requiere solo una.
  • Con REST, se consulta o mucha o muy poca data. Con GraphQL se consulta exactamente lo que se necesita.
  • REST por lo general se convierte en un laberinto de endpoints mal documentados. GraphQL es altamente tipado y auto-documentado.

En las palabras del equipo responsable de la plataforma en GitHub:

GraphQL representa un masivo salto en el desarrollo de API’s. Tipado seguro, introspección, documentación generada y respuestas predecibles, van a beneficiar tanto a los desarrolladores como a los consumidores de nuestra plataforma. Ansiamos una nueva era de plataformas respaldadas por GraphQL y esperamos que ustedes también.

¿Cómo se ve?

Si se firma el acuerdo de pre-release, tendremos acceso al explorador de API’s. Es básicamente GraphiQL, un IDE para explorar API’s GraphQL.

La primera consulta de prueba.
La primera consulta de prueba.

Después de un par de segundos experimentando, mi primera consulta me devuelve una respuesta –Funciona!. Se puede consultar la documentación del API para saber cuáles mutaciones o consultas se pueden hacer. Es básicamente lo esperado: Se pueden buscar usuarios, organizaciones y obtener información de nuestra propia cuenta GitHub.

Obteniendo información de mis Repos
Obteniendo información de mis Repos…

Y claro, también realicé un comentario desde el API!:

Comentar desde el API? Hell yeah!
Comentar desde el API? Hell yeah!

¿Cómo Aprender?

Si GraphQL te emociona como a mi, entonces probablemente estarás preguntándote la mejor manera de implementarlo en tus proyectos. Acá dejo algunos recursos y tutoriales para comenzar.

Tutoriales:

Recursos:

Generar Servicios RESTful a partir de Modelos de Datos

Al momento de desarrollar aplicaciones, casi siempre el punto de partida es la creacion del modelo de datos (y la base de datos). Una vez que tenemos un hogar para nuestras data, el siguiente paso natural es querer generar servicios RESTful para que sean consumidos por nuestras aplicaciones clientes; bien sea un website o un app móvil.

Es entonces cuando nos encontramos con muchísimas opciones para el desarrollo de nuestros servicios. Plataformas, tecnologías, lenguajes de programación, entre otros. Sin duda alguna, puede ser complicado y tardado el comenzar a desarrollar nuestras API’s. En este post trato de comentar mi experiencia con diferentes servicios de generación automática de servicios REST.

Pero primero un disclaimer: Ningún generador nos va a proveer de servicios perfectamente personalizado y según las necesidades particulares. La idea es darnos un comienzo rápido con las conexiones a la BD, el manejo de rutas y la selección de datos de nuestras tablas. Esto quiere decir que las uniones y transformaciones de datos quedan de nuestra parte.

Sin mas preambulos, les dejo las opciones que he probado:

Apiplug: Apiplug es un SAAS (Software Como Servicio) que ofrece la generacion de API’s partiendo de un esquema definido o una BD existente, por un precio. Las opciones de tecnologías justo ahora varían entre PHP5+Laravel5.1, PHP7+Laravel5.2, NodeJS+Express y Python3+Django. Tambien ofrecen ayuda para desplegar los proyectos y como extra, puedes generar un proyecto Android que haga uso de tu recién generado API.

Dashboard de Apiplug
Dashboard de Apiplug

Apigility: Apigility es un proyecto de Zend Framework que debes correr en una intancia de WAMP/XAMPP antes de que puedas llegar a las pantallas de generacion. Una vez allí, ofrece exactamente lo requerido con muy buenas posibilidades de personalización. EL detalle: Naturalmente, el proyecto generado es exclusivamente en PHP.

En futuras actualizaciones, agregare un par de opciones mas a la lista.

Compartir consultas de prueba para Servicios REST con Postman

Postman es una excelente aplicación/extensión de navegador gratuita, que permite realizar consultas a servicios REST desde una agradable (y muy personalizable) interfaz gráfica.

Postman Logo

Su headline es:

Postman helps you develop APIs faster.

Postman UI Screenshot
Postman UI

La verdad es invaluable a la hora de desarrollar API’s, pues facilita las actividades de probar endpoints, cambiar parámetros, seleccionar métodos, configurar tipos de contenido (Content-Type's) y realizar pruebas automatizadas en base a la respuesta del backend.

Una funcionalidad que me ha resultado imprescindible al momento de desarrollar API’s en equipos de desarrollo extendidos, es la capacidad de Postman de guardar y compartir las «Colecciones» (Agrupaciones de consultas, incluyendo rutas, métodos y contenido) con nuestros colaboradores. Acá les dejo los pasos para realizarlo:

  1. Iniciar sesión en Postman Web. https://app.getpostman.com/dashboard
  2. Guardar las consultas en colecciones (y opcionalmente, en carpetas)
  3. Ubicar la colección deseada, hacer click en el menú de puntos al lado
  4. En la lista desplegable, seleccionar «Share»
  5. Seleccionar «Run in Postman Button»
  6. Compartir el botón en nuestro site o Wiki corporativo.

El resultado final es algo del estilo:

Botón Postman en Wiki
Botón Postman en Wiki

Espero les sea útil!