Belvo

Cómo construir una API que enamore a los desarrolladores

Giuseppe

Giuseppe

Compartir

Cómo construir una API que enamore a los desarrolladores

El producto principal de Belvo es un conjunto de APIs fintech que conecta a los usuarios con sus datos bancarios, financieros y fiscales. El nuestro es principalmente un producto basado en una API, es decir, que se consume a través de los endpoints de una API y que se utiliza como componente para construir productos de terceros. Como la mayoría de los productos API, Belvo es un producto para empresas (B2B).

Pero, construir una API plantea algunos retos peculiares. El más obvio es, sin duda, el esfuerzo inicial de integración que requiere para utilizarlo. Cuando una nueva empresa adopta Belvo, su equipo de desarrollo debe encargarse de la integración de nuestra plataforma en su producto. Y esto normalmente implica recursos escasos como ingenieros, PMs, diseñadores y un preciado tiempo para ejecutar su roadmap. 

Dado lo crítico que puede ser este proceso de integración inicial, debe desarrollarse de la forma más fluida y eficiente posible. Además de la propia API, un buen producto API debe complementarse con herramientas, recursos y documentación para minimizar cualquier posible fricción y proporcionar a los desarrolladores total autonomía.

Este artículo cubre lo que creemos que compone el kit de herramientas básico de un producto API, y que nosotros hemos ido implementando desde que lanzamos Belvo en 2020. Es decir, las herramientas que hemos construido para Belvo más allá de la propia API.

Experiencia de autoservicio para desarrolladores

Cuando empezamos a construir la API de Belvo, nos sentamos a entender cuáles eran los recursos más importantes que necesitaríamos incorporar al producto desde el «día 1» para que el proceso de integración fuera lo más fluido posible. Nos fijamos en empresas como Stripe y Twilio y tratamos de entender lo que tenían en común y cómo ofrecían tan buena experiencia de desarrollador.

El dashboard para desarrolladores de Belvo.

Lo que todas las grandes empresas de APIs tienen en común es su enfoque en que la experiencia de desarrollador, las herramientas y los procesos sean ‘self-service’ (o de autoservicio). 

A ningún ingeniero le gusta pasar por múltiples pasos y llamadas con un equipo de ventas para obtener acceso a los endpoints de una API. Ofrecer una excelente experiencia de autoservicio puede marcar la diferencia entre integrar un producto como Belvo en un par de días o convertirlo en un calvario de varios meses.

Construir una verdadera experiencia de autoservicio para desarrolladores implica facilitar operaciones como la configuración de un entorno de prueba (sandbox), la descarga de SDKs, la generación de credenciales de API, el acceso a la documentación, la generación de análisis de APIs y el desarrollo de facilidades para la depuración de errores. Todo tiene que ser accesible a través de un portal para desarrolladores, fácilmente descubrible, y no limitado por ningún formulario de generación de contactos.

Documentación de alta calidad

Siguiendo una filosofía de autoservicio, la documentación de un producto API es una de las primeras cosas que hay que construir junto con la propia API. Una buena documentación de la API debe desarrollarse en dos ejes diferentes: las guías de desarrollo y los documentos de la API.

  • Las guías de desarrollo suelen cubrir temas amplios como «cómo empezar» o «cómo funciona la autenticación» de forma guiada, como un tutorial.
  • Los documentos sobre los endpoints de la API, por otro lado, son materiales de referencia que contienen información detallada sobre cada endpoint de la API, cubriendo entradas, salidas y códigos de error y éxito.

Una cosa que hemos aprendido a lo largo del camino es que, aunque los ingenieros y los product managerspueden escribir documentación, no son especialistas en contenido, y prefieren pasar a desarrollar siguiente funcionalidad en lugar de obsesionarse con la calidad de la documentación. La incorporación de escritores de contenido técnico (o technical content writers) que se centran exclusivamente en la documentación fue un paso importante para mejorar la calidad de nuestra documentación.

También hemos comprobado que, además de las guías de desarrollo y los documentos sobre los endpoints de la API, los desarrolladores valoran contenidos como los ejemplos de guías rápidas de inicio, los ejemplos de código y, sobre todo, una colección de Postman que cubra todos los endpoints de la API con parámetros y valores de configuración precargados. Tener una colección de Postman lista para usar también nos permite ofrecer soporte sobre ejemplos de implementación conocidos, en lugar de indagar en la integración específica de cada cliente.

Building-API-product-Belvo-blog-internal-1
Colección de Postman que cubre todos los endpoints de la API.

SDKs y librerías

Se puede acceder a la mayoría de los productos basados en APIs de dos maneras: directamente a través de los endpoints de la API sin procesar (como REST, GraphQL u otras soluciones) o mediante un SDK o una libreria.

La creación de SDKs para muchos lenguajes de programación tiene un coste, que puede ser aún mayor si tu equipo no está especializado en los lenguajes de programación para los que quieres ofrecer soporte. En Belvo, hemos comprobado que nuestros índices de éxito en las llamadas a la API aumentan hasta un 30% cuando se utiliza un SDK en lugar de la API REST en bruto. Esto nos ha proporcionado una razón de peso para invertir en SDKs en varios lenguajes de programación.

Belvo offers official API libraries for different programming languages, like Python, Ruby and Node.

Creemos que los SDKs de calidad tienen tres propiedades principales:

  • Deben reflejar las necesidades de su base de clientes. Para ello, preguntamos con frecuencia a los clientes y potenciales clientes para qué lenguajes de programación les gustaría tener soporte, y mantenemos una lista priorizada de ellos. 
  • Deben ser idiomáticos. En otras palabras, deben aprovechar las características y construcciones típicas de cada lenguaje de programación.
  • Deben ser de código abierto porque los ingenieros de software quieren ser capaces de controlar los SDKs que incorporan a sus proyectos, inspeccionar su código fuente cuando lo depuran, y tal vez incluso cambiar algunos de sus comportamientos. Como resultado, los SDKs deberían estar disponibles a través de gestores de paquetes como npm, PyPi, o RubyGems para que puedan ser fácilmente incluidos en un pipeline de construcción como cualquier otra dependencia del proyecto.

Un entorno sandbox

Un entorno de pruebas, o sandbox, permite a los desarrolladores probar un producto basado en APIs de forma segura y sencilla, sin afectar a los recursos de producción. Un entorno de este tipo suele tener su propia URL e incluye algún tipo de limitación, como el número de llamadas a la API o algunos valores de respuesta fijados.

Una funcionalidad adicional que puede ofrecer el entorno sandbox es la capacidad de reproducir mediante programación tanto las condiciones del mundo real como las situaciones de error simuladas y diversos casos límite.

Por ejemplo, cuando se pasan ciertos parámetros específicos al entorno de pruebas de Belvo, éste desencadenará respuestas de error sintéticas, devolverá datos simulados especialmente elaborados o ejecutará otra lógica de negocio específica que podría ser difícil de reproducir de forma fiable de otro modo.

El sandbox es tan importante como el entorno de producción. Se podría argumentar que un error en un entorno de pruebas es mucho más costoso que en producción. Esto se debe a que los clientes potenciales suelen utilizarlo para evaluar si desean utilizar un determinado producto API y, por lo tanto, cada error puede ser un factor decisivo.

Un panel de control para desarrolladores

Es importante proporcionar a los desarrolladores un lugar donde puedan entender cómo se comportan sus aplicaciones y cómo funcionan sus llamadas a la API, especialmente cuando se trata de un gran número de llamadas. Esto incluye los códigos de respuesta, opciones de depuración y otra información técnica.

Construir una API
El panel de desarrolladores de Belvo

Contar con un dashboard o panel de control para desarrolladores se ha convertido en algo común en los productos basados en APIs. Es algo que una plataforma debe ofrecer para que los desarrolladores no se vean en la necesidad de reinventar la rueda y desplegar sus propias herramientas de análisis y de depuración de la API. 

Estas son algunas de las características básicas que debe ofrecer un buen panel de control para desarrolladores:

  • Gestión de credenciales y configuración del entorno
  • Análisis de la API
  • Solución de errores
  • Depuración interactiva (por ejemplo, generar y reaccionar ante eventos sintéticos)

Necesitamos tu ayuda 😊 

En Belvo, trabajamos continuamente para mejorar la experiencia de los desarrolladores en la plataforma. Nos apasiona crear una plataforma que sea fácil de usar, que ofrezca las herramientas adecuadas y que dé a los desarrolladores la autonomía que necesitan para crear aplicaciones rápidamente.

Si estos temas despiertan su interés, no dudes en consultar nuestra página de carreras. Actualmente estamos buscando varios perfiles. 

Compartir

Estamos deseando saber qué vas a construir