Integrando una API en Ruby on Rails
En Unagi solemos realizar capacitaciones internas sobre nuevas tecnologías y herramientas, o bien sobre prácticas que entendemos que pueden llegar a ser importantes para el desarrollo de nuestros sistemas. En esta oportunidad, vimos necesario armar una pequeña capacitación sobre cómo integrar una API externa desde Ruby on Rails. Bajo esa premisa, decidimos usar como caso de ejemplo al Tracker, un sistema interno que usamos para la planificación de proyectos, el cual requería de la integración de una API externa de feriados de la Argentina.
No es la primera vez que implementamos una comunicación con una API, ya que es muy común que cualquiera de nuestros sistemas necesite integrarse con alguna de ellas. Incluso comunicamos varias de nuestros propios desarrollos mediante API, así que es algo que utilizamos mucho. Podemos citar algunos ejemplos que ilustrarían bien la situación:
- Pinta Libre (aplicación por suscripción): Se conecta con las API de Mercado Pago y de Stripe para el procesamiento de pagos, con la API interna de IlPostino para el envío de emails, y con las API de Google y Facebook para validar a los usuarios registrados mediante red social.
- Sistemas de gestión contable: Varios de nuestros clientes necesitan integración de facturación de AFIP, por lo que se conectan con la API de Factura Electrónica, la cual es interna de Unagi y sirve para facturar electrónicamente en AFIP.
- eVisa (sistema de trámites migratorios): Se conecta con diversas APIs de los gobiernos para trámites migratorios.
En fin, podríamos enumerar prácticamente la totalidad de proyectos de la empresa, pero queda claro el fundamento de esta capacitación: es importante saber integrar una API en un backend.
Por lo tanto, dado que amamos a Ruby y a Rails, contamos con muchas gemas que nos facilitan la tarea. Sin embargo, antes tenemos que empezar con algunas cosas un poco más básicas.
Documentación de una API
El punto de partida para integra una API es saber para qué sirve, por qué la necesitamos y cómo nos conectamos con ella. Sin una documentación clara, es imposible integrar una API en cualquier sistema, por lo tanto es muy importante leer bien su documentación y familiarizarnos con los diferentes endpoints de la misma. Para quienes no lo sepan, un endpoint de una API es una punto de contacto que tenemos con la misma, a través del cual nos comunicamos con ella, y generalmente se trata de una URI con sus respectivos parámetros.
Las API se pueden consumir de dos formas principales según su implementación: REST y SOAP. No es relevante para este artículo analizar las diferencias de cada una de ellas, por lo que vamos a hacer hincapié en la conexión con REST. Por su parte, una API REST puede manejar diferentes formatos de entrada y de salida, siendo los más comunes JSON o CSV.
Una vez obtenida y analizada la documentación, tenemos que detectar qué endpoints nos sirven para nuestra tarea. No es necesario integrar todos los endpoints de una API, ya que quizás unos pocos nos sirven.
Pruebas de una API REST
Un buen punto de partida para las pruebas de una API REST es usar herramientas que permitan realizar llamados HTTP configurando verbo HTTP, URI, parámetros, cabeceras y cuerpo, entre otra infinidad de variables. En ocasiones, los requisitos de las API pueden resultar algo complejos, como por ejemplo el agregado en cada solicitud de una cabecera de autenticación con una clave generada mediante algún algoritmo de encriptación que utilice el timestamp actual.
Una herramienta muy potente y popular para esto es Postman, la cual permite hacer todo lo anterior, e incluso almacenar y documentar colecciones de llamados a endpoints. Además, tiene capacidades colaborativas, por lo que es muy útil para compartir colecciones o respuestas.
Postman sirve también para validar la documentación de una API. Lamentablemente, no todas las API mantienen su documentación actualizada, por lo que Postman puede ayudar mucho a detectar diferencias, principalmente en las respuestas de los endpoints que nos interesan integrar.
Integración en Ruby on Rails
Ruby tiene varias gemas que facilitan la conexión con una API REST, y algunas de ellas están hechas especialmente para el testing en Rails.
En primer lugar, necesitamos seleccionar una gema para que actúe como cliente HTTP y haga los llamados a la API. Podemos usar Net::HTTP de Ruby, pero en nuestra experiencia es algo tedioso y el código resultante no es tan expresivo. Como alternativa, hay algunas gemas muy usadas en la comunidad, entre las que destacamos a Faraday por su simplicidad de uso y su gran aceptación por parte de los desarrolladores. Su documentación es clara e intuitiva, y es muy fácil de integrar. Recomendamos también incorporar la gema faraday_middleware para que el uso de Faraday se vuelva aún más intuitivo y simple.
Adjuntamos algunos links de interés de Faraday de su documentación oficial para aprender cómo utilizarla:
- Uso y generalidades.
- Armado de requests.
- Documentación completa de la API (recomiendo Connection y Response).
Otra parte importante de la integración tiene que ver con sus tests. Es importante que todos los tests de un sistema se ejecuten en un entorno controlado de sandbox, y que ninguna conexión se haga de forma real con un servicio externo. Esto es importante por varios motivos: modificaciones de la base de datos del servicio externo, consumo de cuota de uso o de tráfico de la API, posibilidad de suspensión del servicio por uso continuo o inadecuado.
Por lo tanto, tenemos que asegurarnos que nuestro sistema no haga conexiones reales. Para tal fin, disponemos de la gema WebMock, la cual se encarga de bloquear todos los llamados externos, y ofrece una API para programar respuestas simuladas de una API o servicio frente a una solicitud que haga nuestro sistema. Ofrece soporte para varios frameworks de testing, como RSpec y Minitest, y una serie de helpers que ayudan a verificar desde los tests que los llamados es hagan correctamente.
Prueba en aplicación real
Tal y como se comentó al inicio de este artículo, decidimos usar nuestro Tracker como ejemplo para integrar una API externa. Para hacer más intuitiva la capacitación, decidimos armar un video en donde se integra la mencionada API de feriados al sistema, explicando los diferentes pasos y decisiones que se fueron tomando. El video dura poco más de 1 hora, y repasa los fundamentos citados en este artículo, así como también integra un endpoint de la API con Faraday, implementando sus respectivos tests utilizando WebMock.
Obviamente, el código del video es totalmente refactorizable, pero el propósito era implementar algo simple y entendible con explicaciones en tiempo real. Sin embargo, el código final con todo el refactoring y sus tests se puede encontrar al final de este artículo, y recomendamos revisarlo luego de ver el video.
Aprovechamos la ocasión para agradecerle a Pablo Novas, creador de la API de feriados, y para recomendar el uso de la misma. ❤️
¿Qué te ha parecido el artículo? Nos encantaría escucharte. Si tenés alguna duda, sugerencia o crítica, no dudes en dejar un comentario más abajo. Y si te gustó el artículo, podés hacer click en el ícono de aplauso 👏.
En Unagi (unagi.com.ar) ayudamos a pequeñas y medianas empresas de todo el mundo a diseñar y desarrollar aplicaciones web y móviles. Así llegues con una idea, un problema o un sistema existente, nos calzamos tus zapatos para conocer tu negocio y trabajamos codo a codo para lograr lo que necesitas.
