Web APIs: ¿Por qué debemos conocerlas?

Te ayudamos a realizar tu lista de verificación respecto al uso de APIs, con ejemplos prácticos que te permitirán entender qué aspectos son esenciales para prevenir errores y elegir la más adecuada según los alcances del proyecto.

Hoy usamos las APIs en todo momento y casi sin saberlo. Por ejemplo, usamos APIs cuando nos logueamos con Facebook o Google en alguna Web App, cuando conectamos Slack con Gmail o al decirle a Amazon Echo que reproduzca nuestro playlist favorito de Spotify. Sí, también cuando subimos una foto a Instagram y, en paralelo, se publica en Twitter y Facebook.

Ciertamente la lista de integraciones disponibles y que podemos usar de manera cotidiana es larga y, como usuarios, no tenemos que saber que todas esas integraciones son gracias a las APIs. De hecho, ni siquiera tenemos que saber qué es una API, ni tampoco saber cómo programar una. Sencillamente, transitamos entre redes de forma rápida gracias a ellas.

Las APIs están ahí y nos pueden ayudar en mucho más

Probablemente en alguna reunión de trabajo los informáticos de T.I. han hablado de solucionar algún requerimiento con una API. Cuando esto sucedió, seguramente entendimos poco de lo que han dicho, aunque parecía ser la solución más sencilla y práctica. Al hacerlo, todos han quedado satisfechos, pero nadie sabe a ciencia cierta qué hará T.I., ni cuánto demorará.

En este contexto, es importante saber algunas cosas mínimas sobre las APIs. Saber, por ejemplo, qué es un método y un endpoint; diferenciar entre XML y JSON, o entender que cuando hablamos de método y función, nos referimos prácticamente a lo mismo. Estos conocimientos mínimos nos ayudarán a definir mejor el alcance de nuestro requerimiento y a estimar de mejor forma tiempos y presupuestos, sin minimizar ni sobredimensionar, los esfuerzos.

Entonces qué es un API

De manera simple, podemos decir que es un protocolo que, mediante un lenguaje común, permite intercambiar información y ejecutar tareas remotas entre dos plataformas distintas, programadas en lenguajes diferentes.

Este protocolo determina tres cosas:

1. La información que se recibe, bajo qué método y formato.
2. Qué rutina, tarea o función se ejecuta, es decir, qué hará con la información recibida.
3. Cuál será la respuesta que recibirá una vez ejecutada la tarea. En qué formato y estructura nos entregará los datos resultantes de una tarea ejecutada correctamente o nos dirá si hubo un error.

Existen varios protocolos o especificaciones. Los más populares hoy son SOAP y RESTful, aunque en los últimos años GraphQL ha ido ganando cada vez más adeptos.

Si trabajamos con SOAP entendemos que el lenguaje común para intercambiar información será XML y que se usará un documento XML especial, llamado WSDL. El cual describe tanto los métodos -rutinas o funciones- del servicio, como los parámetros que recibe y devuelve cada método.

Si trabajamos con REST, en cambio, sabemos que utilizaremos mayoritariamente JSON para intercambiar información. Además, usaremos cabeceras POST, PUT, UPDATE y DELETE para informar un cambio de estado. También, utilizaremos peticiones GET con Query Strings para conseguir datos y que será imprescindible (a falta de un WSDL) una documentación para conocer las URLs de cada uno de los endpoint correspondientes a cada una de las funciones que necesitamos ejecutar. Así como la descripción de cada parámetro que recibe y devuelve esos endpoint.

Una API ¿Es la mejor solución?

Es probable que con el correr de las semanas y de los meses, aparezcan algunos problemas en su implementación. Por ejemplo, si quienes consumen la API no son los mismos desarrolladores que la construyeron, no cuesta mucho imaginar que los primeros no puedan seguir avanzando, porque la API no está terminada y porque los desarrolladores no han documentado nada de lo que han hecho.

Una API pequeña, que cumple una sola función, puede ser algo simple y rápido de construir; pero una API que dispone de múltiples endpoints y que expone -por decirlo de algún modo-, muchas de las funciones complejas de una plataforma, puede tardar bastante más en desarrollarse.

Depende de la función

Resulta que en una API extensa, muchas de sus funciones están interconectadas y cumplen con algo más que los requisitos mínimos de seguridad. Además, cada uno de los endpoints deberá ser testeado según los múltiples casos de usos que se plantearon en la definición de alcances. Así, cualquier desarrollador puede usarla, mientras que en paralelo se ha ido documentando debidamente cada uno de los métodos programados.

Para que no quepan dudas, se debe programar, testear y documentar prácticamente a la par. Y no hay que olvidar que se deben cumplir ciertos alcances mínimos, o ciertos casos de uso, que por obvios que parezcan al sentido común, no necesariamente los son para un programador que se guía por documentos con definiciones de alcances precisas y detalladas.

Vemos un ejemplo. El requerimiento es que necesitamos conectar un formulario de contacto en el sitio web con un CRM propietario. El sitio está en WordPress en un servidor de Amazon y el CRM, en un servidor montado en una LAN de T.I. En el sitio web, el formulario tiene cuatro campos: nombre, email, tema y mensaje, donde el campo tema es un selector con las opciones sugerencia, reclamo y felicitaciones.

Cuando lo sencillo se complica

En principio, pareciera ser todo muy sencillo, pero resulta que el desarrollador a cargo de levantar el API decidió innovar un poco y el endpoint que programó recibe en el body un JSON de 6 parámetros: name, email, subject, message, status y token. En este caso, el subject acepta valores integrales (1, 2, 3); status acepta un booleano y el campo name solo acepta un strings de máximo 15 caracteres.

De un momento a otro, aparece un lenguaje técnico con el que hay que familiarizarse rápidamente para comprender y verificar si se están satisfaciendo los alcances definidos para esta API y si las estimaciones iniciales de esfuerzos sufrirán variaciones significativas.

Es cierto que la jerga técnica hace que todo se perciba como más complejo, pero es necesario superar esa barrera para -en jerga deportiva- poner la pelota sobre el césped y dejar las piruetas de lado. En este punto la documentación es clave.

Saber documentar y crear en base a los alcances del proyecto planteado, es fundamental. Para ello, tener claro las responsabilidades del equipo, ayudará a cumplir sus objetivos. Desde la experiencia, podemos decir que esas responsabilidades se dividen entre mandante o gerencia y T.I. y deben preocuparse de:

- Ejecutivos / Mandante / Gerencia: Entender lenguajes de programación básicos o conceptos utilizados en el desarrollo para estar informado sobre cómo se construirá el proyecto y alinearlo con los alcances establecidos.

- TI / Equipos de desarrollo: crear, documentar y testear las herramientas construidas, con énfasis en registrar lo desarrollado y sus posibles alcances.

Lo mínimo de una documentación para un API

Si no hay documentación, los problemas que tendrá el desarrollador que está haciendo la integración con CRM serán varios.

Problemas comunes de la ausencia de documentación

- Qué tipo de API se está usando

1. Si es SOAP cuál es la URL del WSDL y cuál es el método a usar.
2. Si es RESTful cuál es la URL del endpoint

- ¿Cómo entregar los parámetros? ¿En un JSON o XML, por POST, PUT o con GET y query strings?

Luego, al despejar estas dudas iniciales, seguirán:

1. El formulario envía los campos nombre, email, tema y mensaje pero no se guarda nada en CRM.

2. ¿Se necesita un token?

• ¿Cómo se obtiene o genera el token?.
• Cada cuánto tiempo se requiere validarlo.

3. Todos los contactos quedan con subject 1 o "sugerencia".

4. Todos los contactos quedan con status false y en el CRM quedan en la papelera.

5. Hay contactos que nos se guardan o quedan, en el mejor de los casos, sin nombre.

Sin documentación no hay integración

Todos estos problemas evidencian que la documentación es tan o más importante que la programación misma del API. Sin documentación prácticamente no hay integración posible. En nuestro ejemplo el desarrollador no ha sido informado de los elementos esenciales para hacer su trabajo:

1. ¿Se usará uno o varios endpoints?
2. ¿Cuáles son las URLs de los endpoints?
3. ¿Qué tipo de API que usará? y, en consecuencia, ¿cuál es el formato para intercambiar información?
4. ¿Cuál es la descripción y detalle de los campos que necesita enviar al API?
5. ¿Qué descripción y detalle de campos recibirá de vuelta del API?

En ese contexto, la documentación requerida es sencilla, pero imprescindible. Bastaría con algo como lo que sigue:

Pero eso no es todo, luego viene el problema de que en el formulario hay cuatro campos con nombres en español y el CRM necesita 6 con nombres en inglés para funcionar.

Mientras el desarrollador que integra no conozca ese detalle, no tendrá forma de adivinar. En este caso la forma de documentar también es sencilla, se debe indicar por cada parámetro, el tipo, extensión mínima y máxima, si es obligatorio y si se necesita usar otro endpoint para conseguir o formatear un dato.

Con esta tabla simple el integrador vería de manera rápida y sencilla qué hacer para hacer funcionar la integración, tiene que resolver aún algunos problemas:

1. Cambiar los nombres de los campos a los requeridos por el CRM.
2. Limitar a 15 caracteres el campo nombre, dado que en CRM no se guardarán aquellos que excedan esa extensión.
3. Para el tema o subject necesita una tabla de conversión.
4. Enviar un valor booleano para status (0 ó 1)
5. Y conseguir un token en el método obtener_token

Todos estos puntos deberían venir igualmente documentados, por ejemplo:

Tabla de conversión para valores de subject.

Este caso aparentemente es de una obviedad y sentido común casi exagerado, pero la verdad es que no es así. Los valores 1, 2 y 3 son absolutamente arbitrarios, bien pueden ser 100, 200 y 300 o tener una asociación distinta. Además, si el integrador ignora que debe entregar un integral en vez de un string, existe una alta posibilidad de que el string sea siempre interpretado como 1.

En el caso del token la documentación es similar. Se indica el endpoint, el método de acceso (que en REST es distinto al concepto método de función) y los parámetros de entrada y salida.

Token

Parámetros GET

ID de clientes en ambientes Dev y Prod

cliente_id ambiente desarrollo: 1111222233334444
cliente_id ambiente producción: 4598357495464685

Detalle de respuesta JSON

Finalmente el último problema por dilucidar y que no resiste mucho análisis, es que los posibles casos de uso para ingresar nombres con extensiones mayores a 15 caracteres son probablemente mayoritarios. En tal caso, solucionar esto depende de una corrección que deberá realizarse en el CRM y no en la integración ni en el formulario mismo.

Algo similar debiese ocurrir con el campo status, que desde el punto de vista del sitio web, claramente se puede omitir por cuanto obedece a una lógica interna del CRM y no es vinculante con el sitio.

Conocimiento es poder

En la práctica, conocer cuál es el objetivo de implementar una API en un proyecto, y saber en detalle, de qué forma fue ejecutada, nos beneficiará enormemente. Desde la optimización de tiempos, a la prevención de errores y por supuesto, su correcto funcionamiento.

Antes de utilizarlas, definitivamente debemos conocerlas.

Artículo publicado junto a Max Villegas.
Originally published at https://blog.ida.cl on September 25, 2020.