OpenAPI: interfaces de programación de aplicaciones para máquinas (1)

Tanto un agricultor que produce cacao en la selva como una empresa de servicios financieros, son organizaciones empresariales que producen datos e información a partir de sus actividades económicas. Lo que diferencia a una de la otra es la sofisticación de la operación. Una familia que se dedica a producir cacao usualmente tiene una extensión menor a 2 hectáreas por lo que su producción no supera las 2 toneladas al año. Este producto se vende principalmente al exterior y por esto el productor debe o bien asociarse o vender su producción a un acopiador para suplir la demanda mínima del cliente final en el extranjero. Esto significa que el agricultor interactúa con no más de 5 o 6 entidades diferentes durante el año, lo cual produce una cantidad manejable de datos que todavía se pueden gestionar en un cuaderno. El precio de referencia internacional del cacao, la compra de insumos, la contratación de obreros para cosecha, la venta al acopiador.

Una empresa de servicios financieros, en cambio, efectúa transacciones cada día con una cantidad no menor de personas. Cada transacción produce datos e información que deberá ser almacenada, organizada y tratada, pues de esto depende la buena salud del negocio. Esta situación, por tanto, es más compleja de manejar de forma analógica, por lo que se deberá recurrir a la mecanización. En este sentido, no es de extrañarse que la industria financiera sea quien ha adoptado las tecnologías de información con mayor avidez desde su aparición en los años 50.

El escenario descrito previamente se ha difundido a tal velocidad en la sociedad que hoy es muy difícil encontrar negocios que todavía gestionen su información en medios analógicos. Los negocios cada vez más intercambian información directamente en un soporte digital. Y aquí, nuevamente, en mayor o menor sofisticación. Un nivel de sofisticación alto es el uso e implementación de interfaces de programación de aplicaciones (API), que no son más que métodos para el intercambio de información. A nivel coloquial, se podría decir que permiten “conversar” a dos aplicaciones. Los hay de todo tipo y presentación, pero las que van predominando los últimos años son las basadas en la web. Se les ha denominado servicios web y dentro de los más populares protocolos para este objetivo están SOAP y REST.

Las interfaces de programación de aplicaciones son comprendidas por una persona, programador de software, y consumidas por aplicaciones que éste construye. Esto significa que quien crea una API debe entregar información o documentación sobre los métodos, tipos de datos, requisitos de la petición, requisitos de seguridad, etc. que se deben cumplir para poder interactuar de manera correcta con tal aplicación. A menudo los programadores de APIs se apoyan en herramientas que permiten documentar lo descrito previamente y producen un portal de desarrollador que sirve de guía y referencia para quien quiera interactuar con la misma. En el caso de los lenguajes de programación como Java, Python, Ruby, NodeJS, PHP y otros que tienen amplia adopción, se puede utilizar piezas de código conocidas como “anotaciones” o “decoradores”, que permiten asignar determinados atributos a otra pieza de código que es la que finalmente implementa un método o función del API, a fin de producir tal documentación de manera semi-automatizada.

Más de una vez se habla de que las máquinas tomarán en control, sin percatarse de un detalle importante, sin embargo, no quiero entrar en la dialéctica Kurzweiliana, sino quiero hablarle de cómo hacer que tus APIs puedan ser comprendidas y utilizadas por otras máquinas. Efectivamente, amigo lector, como lo ha leído. Cada cierto tiempo va tener usted la posibilidad de crear algo desde la nada, es la magia de la informática. Si ese fuese su caso hoy, ¿podría plantearse crear esta nueva aplicación bajo un diseño de API? Es decir, implementar la las capas de persistencia, lógica de negocio y exponer métodos para que se construyan distintas interfaces. ¿Porqué no?

Esta decisión claramente implicaría un nuevo enfoque en la forma en que trabaja su equipo. En principio sería su propio equipo o alguno de sus colegas quien tendría que consumir su propia interfaz de programación. Es decir, consumir lo que usted produce. También se debe plantear el caso en que no sea un programador directamente quien comprenda, aprenda e implemente los programas que interactuarán con ésta. Quizá exista la posibilidad de que un programa pueda hacer todo eso de manera eficiente. En ese caso, ¿cómo sabría el programa qué métodos, tipos de dato, autorización, etc. debe utilizar?

La especificación OpenAPI (OAS), antes Swagger, es una iniciativa que permite a las aplicaciones descubrir y conocer todo lo que permite una interfaz de programación de aplicaciones (API) determinada. Está enfocada principalmente al protocolo REST, SOAP ya cuenta con WSDL para el caso similar. El principal objetivo de OAS es que, cuando se implementa adecuadamente, la implementación del consumidor requiera una cantidad mínima de lógica para utilizarlo. Esto, facilita el que otros programas entiendan y consuman estas interfaces directamente y también permite que las herramientas de generación de documentación puedan producir ejemplos de implementación en diferentes lenguajes de programación. De esta manera es cómo Skynet se plantea el vivir en la red, lejos del hardware.

Al ser una especificación OAS tiene implementaciones en forma de herramientas en diferentes lenguajes de programación. Sin embargo, se debe tener en cuenta de que la especificación es agnóstica del idioma, por lo que esto no es relevante, y por tanto su implementación puede ser uniforme en todos sus proyectos. La idea es que no se necesite mirar el código fuente, la documentación, efectuar análisis de tráfico de red (hola Fiddler), o cosas más esotéricas, y populares en el país del virus, como la denominada ingeniería inversa en los círculos subterráneos de la tecnología, para entender de qué va este bendito API.

En una siguiente edición explicaré cómo hemos llevado un API normalito, del Ruby on Rails de toda la vida, que nos sirve para producir los fantásticos, y muy útiles, gráficos y datos de https://mercados.quinpu.com a uno que podrá ser consumido por una horda de gente que quiere ganar dinero y sabe programar. Hasta luego.

Quinpu es un club de Internet. El lugar donde el punk no ha muerto.