Desarrollo rápido de APIs usando las herramientas de Open Exchange

En este artículo, compartiré el tema que presentamos @Rochael Ribeiro y yo en la Convención Anual (Global Summit) 2023, en la sala "Tech Exchange".

En esa ocasión hablamos de los siguientes temas:

• Herramientas de Open Exchange para Fast APIs (APIs rápidas)
• Especificación OpenAPI
• Desarrollo tradicional vs. Fast API
• APIs Compuestas (Interoperabilidad)
• Enfoque Spec-First o Api-First 
• Gobernanza y Monitorización de APIs
• Demo (vídeo)

Herramientas de Open Exchange para Fast APIs

Como estamos hablando de desarrollo rápido de APIs modernas (Rest / json) utilizaremos dos herramientas de Open Exchange:

La primera es un framework para el desarrollo rápido de APIs, que explicaremos en este artículo.

https://openexchange.intersystems.com/package/IRIS-apiPub

La segunda es utilizar Swagger como interfaz de usuario para la especificación y documentación de las APIs Rest desarrolladas en la plataforma IRIS, así como su uso/ejecución. La base de su funcionamiento es la especificación OpenAPI (OAS) estándar, que se describe a continuación:

 https://openexchange.intersystems.com/package/iris-web-swagger-ui

 

¿Qué es la especificación OpenAPI (OAS)?

Es un estándar utilizado en todo el mundo para definir, documentar y consumir APIs. En la mayoría de los casos, las APIs se diseñan incluso antes de su implementación. Hablaré más de ello en los próximos apartados.

Es importante porque define y documenta las APIs Rest para su uso, tanto en el lado del proveedor como del consumidor. Pero este patrón también sirve para agilizar las pruebas y las llamadas a las API en las herramientas (Clientes de las APIs Rest) del mercado, como Swagger, Postman, Insomnia, etc…

 

Forma tradicional de publicar APIs utilizando IRIS

Imaginemos que tenemos que crear y publicar una API Rest a partir de un método IRIS existente (imagen inferior).

De la forma tradicional:

1: Tenemos que pensar cómo la llamarán los consumidores. Por ejemplo: Qué ruta y verbo se utilizará y cómo será la respuesta. Ya sea en un objeto JSON o como texto plano.

2: Crear un nuevo método en una clase %CSP.REST que administrará la solicitud http para llamarlo.

3: Gestionar la respuesta del método a la respuesta http prevista para el usuario final.

4: Pensar cómo vamos a proporcionar el código de respuesta y cómo vamos a gestionar las excepciones.

5: Mapear la ruta para nuestro nuevo método.

6: Proporcionar la documentación de la API al usuario final. Probablemente crearemos el contenido OAS manualmente.

7: Y si, por ejemplo, tenemos una carga útil (objeto) de solicitud o respuesta, el tiempo de implementación aumentará, porque también debe documentarse en OAS.

 

¿Cómo podemos ser más rápidos?

Simplemente etiquetando el método IRIS con el atributo [WebMethod]. Sea lo que sea, el framework se encargará de su publicación, utilizando el estándar OAS 3.x.

¿Por qué es tan importante el estándar OAS 3.x? 

Porque también documenta detalladamente todas las propiedades de las cargas útiles de entrada y salida.

De esta forma, cualquier herramienta Rest Client del mercado puede acoplarse instantáneamente a las API, como Insomnia, Postman, Swagger, etc. y ofrecer un contenido de muestra para llamarlas fácilmente.

Usando Swagger ya visualizaremos nuestra API (imagen superior) y la llamaremos. Esto también es muy útil para realizar pruebas.

Personalización de la API

Pero, ¿y si necesito personalizar mi API?

Por ejemplo: En vez del nombre del método, quiero que la ruta sea otra cosa. Y quiero que los parámetros de entrada estén en la ruta, no como un parámetro de consulta.

Definimos una notación específica en la parte superior del método, donde podemos complementar la metainformación que el propio método no proporciona.

En este ejemplo estamos definiendo otra ruta para nuestra API y complementando la información para que el usuario final tenga una experiencia más amigable.

Mapa de proyección para APIs Rest

Este framework soporta numerosos tipos de parámetros.

En este mapa podemos destacar los tipos complejos (los objetos). Se expondrán automáticamente como una carga útil JSON y cada propiedad estará debidamente documentada (OAS) para el usuario final .

 

Interoperabilidad (APIs compuestas)

Al admitir tipos complejos, también se pueden exponer servicios de interoperabilidad.

Es un escenario favorable para crear APIs compuestas, que utilizan la orquestación de múltiples componentes externos (salidas).

Esto significa que los objetos o mensajes utilizados como solicitud o respuesta serán publicados y leídos automáticamente por herramientas como swagger.

Y es una forma excelente de probar componentes de interoperabilidad, porque normalmente ya se sube una plantilla de carga útil para que el usuario sepa qué propiedades utiliza la API.

En primer lugar, el desarrollador puede centrarse en las pruebas y, a continuación, dar forma a la API mediante la personalización.

Enfoque Spec-first o Api-first

Otro concepto muy utilizado hoy en día es tener la API definida incluso antes de su implementación.

Con este framework es posible importar una especificación OpenAPI. Crea la estructura de los métodos (especificación) automáticamente, y faltaría sólo su implementación.

Gobernanza y monitorización de APIs

Para la gobernanza de las APIs, también se recomienda utilizar conjuntamente IAM.

Además de disponer de múltiples plugins, IAM puede acoplarse rápidamente a las APIs a través del estándar OAS.

apiPub ofrece trazabilidad adicional para las APIs (ver el video demostración)

Demostración

https://www.youtube.com/embed/IdJ1PqmhH3c
[Este es un enlace integrado, pero no puede ver el contenido integrado directamente en el sitio porque rechazó las cookies que se necesitan para acceder a él. Para ver el contenido integrado, debe aceptar todas las cookies desde la Configuración de cookies]

Descarga y documentación

Intersystems Open Exchange: https://openexchange.intersystems.com/?search=apiPub

Documentación completa: https://github.com/devecchijr/apiPub