Header Ads Widget

Ticker

6/recent/ticker-posts

Revisión de herramientas: AsyncAPI



La documentación lo liberará : este es un mantra que suelen ser entregados por desarrolladores experimentados y vale la pena repetirlo cada vez que se discute el valor de la documentación . En pocas palabras, la documentación es quizás uno de los elementos más importantes de la comunicación efectiva del desarrollador de API, solo superado por demostraciones activas, tutoriales y otros sistemas interactivos. Incluso entonces, en la mejor de las implementaciones, esos sistemas se basan activamente en la documentación generada por el desarrollador, proporcionando así un valor cada vez mayor.

Revisamos AsyncAPI, una especificación legible por máquina.

Es lamentable, entonces, que no toda la documentación sea igual. Si bien el valor de la documentación es bien conocido, la forma en que se crea la documentación es tan variada como la propia industria API. Esto es especialmente evidente una vez que se sale de la industria de microservicios de API RESTful clásica y se introduce en otros tipos de tendencias de diseño de API . Hoy, vamos a revisar una herramienta llamada AsyncAPI que ha surgido de esta realidad tan clara.

Creado por el anterior orador de API nórdicas  Fran Méndez , AsyncAPI llena un vacío entre la sintaxis de documentación legible por máquina para API generales y el diseño arquitectónico basado en mensajes que aún impulsa una amplia gama de servicios y sistemas. Con esto en mente, ¿qué es exactamente AsyncAPI? ¿Qué hace y, lo que es más importante, cómo lo hace?

Qué hace AsyncAPI

AsyncAPI se acerca a la documentación basada en mensajes asumiendo dos conceptos básicos principales. Primero, establece que los mensajes impulsan casi todas las interacciones de API y que estos mensajes son un evento o una acción. Si bien fomentan la diferenciación entre esos dos tipos de mensajes, la separación no está claramente definida o ni siquiera es necesaria. Por lo tanto, todo lo que hace AsyncAPI se basa en el concepto de un sistema de mensajes generalmente definido en el que el mensaje contiene un encabezado y una carga útil, los cuales son opcionales y pueden existir como cualquiera de los tipos de mensajes.

En segundo lugar, AsyncAPI asume que estos mensajes se clasifican en términos generales en un tema, generalmente utilizando MQTT , AMQP o STOMP , que son todos métodos de sintaxis "orientados a temas" para definir a qué se refieren los mensajes. Estos son ampliamente análogos a las URL en las API HTTP clásicas: cuando se envía un mensaje a la API, se enruta en función del tema, como se indica en su orden de publicación.

Con estos dos supuestos, AsyncAPI comienza a formular una especificación para traducir este contenido a formatos legibles por máquina de una manera eficiente y efectiva. AsyncAPI permite la definición (o falta de definición) de cualquier encabezado del mensaje que se envía, lo que permite un total agnosticismo del protocolo . Esto permite que el código legible por máquina que resulta de este proceso se lea en una amplia variedad de sistemas utilizando MQTT, AMQP o cualquiera de los otros métodos de amplio rango para manejar los mensajes correctamente.

Las API se pueden describir utilizando JSON o YAML para una máxima legibilidad de la máquina, y tiene la capacidad de vincularse a las GUI para la legibilidad humana a partir del código orientado y generado por la máquina. Esto permite que tanto las máquinas como los humanos lean el código y comprendan lo que está sucediendo, además de identificar tanto el tipo, el contenido y el tema del mensaje en sí.

Finalmente, AsyncAPI es completamente de código abierto . Si bien se pueden argumentar a favor del valor del desarrollo tanto de código cerrado como de código abierto, tener una solución de código abierto generalmente significa mayor seguridad a través de la inspección comunitaria, mayor eficiencia a través de la optimización colectiva y una verificación de errores más efectiva mediante pruebas masivas.

Lea esta publicación de Fran, creador de AsyncAPI: API asíncronas en microservicios coreografiados

Por qué ayuda la API Async

La documentación legible por máquina tiene muchos beneficios. En primer lugar, tener un código legible por máquina significa que la documentación resultante será, en última instancia, más fácil de usar como fuente para otros recursos generados. En última instancia, esto también significa una mejor generación de código , ya que se pueden crear nuevas estructuras y clases automáticamente a partir del código. También existe el argumento de que trabajar en un sistema legible por máquina permite un escalado más fácil y efectivo , ya que la cantidad más óptima de recursos en la configuración más óptima se puede encontrar mucho más fácilmente de una manera más automatizada.

En total, la documentación legible por máquina es enormemente beneficiosa. Cuando los desarrolladores de AsyncAPI querían aprovechar estos beneficios para sus propios sistemas internos, encontraron una brecha entre las API HTTP clásicas y las implementaciones de diseño RESTful de implementaciones legibles por máquina y la arquitectura basada en mensajes de sus sistemas internos. Debido a que los microservicios basados ​​en mensajes son específicos en términos de estructura y enfoque, las soluciones tradicionales no se ajustaban del todo bien a sus implementaciones y se requería un nuevo método.

Este fue el nacimiento de AsyncAPI. La forma en que se forma la especificación permite una mayor interoperabilidad y herramientas específicamente para arquitecturas impulsadas por mensajes y , como tal, llena un sector a menudo ignorado de la industria API. Solo por esta razón, y mucho menos por sus metodologías efectivas e implementaciones eficientes, vale la pena echarle un vistazo a AsyncAPI.

¿Cómo funciona AsyncAPI?

Ahora que entendemos en qué ayuda AsyncAPI, y específicamente qué brecha llena, ¿cómo funciona AsyncAPI ? Para empezar, conviene señalar que AsyncAPI se basa generalmente en el esquema JSON y se compone de cuatro partes: Información de API , Servidores , Temas y Componentes . Para empezar, se crea un archivo de descripción simple, normalmente llamado asyncapi.ymlEste archivo tiene definidas las cuatro partes de sintaxis.

En primer lugar, es necesario definir los elementos de información de la API , también denominados objeto de información . Este objeto indica el título de la API, su descripción, términos de servicio, detalles de contacto, etc. Esto es esencialmente lo que dice en la lata y forma la identidad básica de la API en su conjunto.

El objeto de información se parece a esto:

{
 "title": "AsyncAPI Sample App",
 "description": "This is a sample server.",
 "termsOfService": "http://asyncapi.org/terms/",
 "contact": {
   "name": "API Support",
   "url": "http://www.asyncapi.org/support",
   "email": "support@asyncapi.org"
 },
 "license": {
   "name": "Apache 2.0",
   "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
 },
 "version": "1.0.1"
}

Una vez que se indica el objeto de información, es necesario crear el objeto Servidores . Este elemento define las URL del servidor, sus descripciones y el esquema que se utiliza para manejar los mensajes dentro de la arquitectura. La declaración del esquema es extremadamente importante aquí y permite una solución independiente del protocolo a nivel de servidor. Este elemento normalmente se parece al ejemplo siguiente, que usa MQTTS :

{
"servers": [
{
"url": "development.gigantic-server.com",
"description": "Development server",
"scheme": "mqtts"
},
{
"url": "staging.gigantic-server.com",
"description": "Staging server",
"scheme": "mqtts"
},
{
"url": "api.gigantic-server.com",
"description": "Production server",
"scheme": "mqtts"
}
]
}

Ahora que nuestros servidores están definidos, así como también cómo se manejan los mensajes en esos servidores, podemos establecer el elemento Temas . Los temas son el método esencial mediante el cual los mensajes se agrupan y organizan y, como se dijo antes, son aproximadamente análogos a las URL de la API HTTP .

En el siguiente ejemplo, se define un tema para AsyncAPI.

{
"accounts.1.0.event.user.signup": {
"subscribe": {
"$ref": "#/components/messages/userSignedUp"
}
}
}

Finalmente, podemos definir Componentes . Los componentes son conjuntos de objetos reutilizables que se pueden utilizar para definir y limitar los mensajes que se envían a lo largo de la implementación. En el siguiente ejemplo, tenemos varios objetos con diferentes tipos y formatos que permiten la adición de un usuario:

"components": {
"schemas": {
"Category": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
}
},
"Tag": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
}
}
},
"messages": {
"userSignUp": {
"summary": "Action to sign a user up.",
"description": "Multiline description of what this action does.\nHere you have another line.\n",
"tags": [
{
"name": "user"
},
{
"name": "signup"
}
],
"headers": {
"type": "object",
"properties": {
"qos": {
"$ref": "#/components/schemas/MQTTQoSHeader"
},
"retainFlag": {
"$ref": "#/components/schemas/MQTTRetainHeader"
}
}
},
"payload": {
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/userCreate"
},
"signup": {
"$ref": "#/components/schemas/signup"
}
}
}
}
}
}

¿Qué es una API basada en mensajes?

El código API ha tenido que cruzar la línea entre la funcionalidad de la máquina y la comprensibilidad humana , en gran parte porque los métodos que utilizan la API son a menudo métodos de interacción humana. En otras palabras, los humanos usan las API predominantemente de manera activa y, debido a esto, el código debe entenderse dentro de ese contexto. Como una extensión de eso, las API han ocupado durante mucho tiempo un paradigma de "solicitud y recepción" como se analiza a continuación, extendiendo aún más el problema a implementaciones modernas.

Un enfoque de API basado en mensajes , entonces, no es realmente una "evolución" de estas funciones, sino más bien una especie de regreso a lo básico . AsyncAPI asume que todas las funciones de la API son necesariamente "mensajes" y, como tal, al abordar la API desde una arquitectura basada en mensajes, pueden manejarse mejor de manera neutral en lugar de utilizar herramientas de los puntos finales y la mecánica interna hacia el usuario.

¿Quién encuentra esto útil? ¿Qué piensa la comunidad?

Con todo esto en mente, debemos identificar exactamente quiénes se benefician de este tipo de enfoque. En términos generales, cualquier API que utilice una arquitectura basada en mensajes (y parece que AsyncAPI argumentaría que la mayoría de las funciones de la API se pueden considerar "basadas en mensajes") y desea documentación legible por máquina podría beneficiarse de AsyncAPI.

Específicamente, si las funciones de una API se pueden resumir en el arquetipo del mensaje o se pueden expresar en tal formato, la capacidad de generar más código API, documentación, notas de especificación, etc. es muy valiosa y podría resultar en algunas ganancias importantes.

Planes futuros

Las API nórdicas hablaron con el creador de AsyncAPI, Francisco Méndez Vilas, para evaluar las nuevas características que se pueden esperar en 2.0.0. Esto es lo que tenía que decir:

  1. Un mecanismo para denotar explícitamente desde la perspectiva de quién se debe interpretar la especificación. A diferencia de OpenAPI , el modelo en AsyncAPI no es cliente / servidor, por lo que existe confusión al tratar de comprender quién puede realizar una operación. Por ejemplo, si su documento AsyncAPI dice "publicar", ¿significa que puede publicar en este tema? ¿O significa que el código API se publicará en este tema? El desafío aquí es que ambas respuestas son perfectamente válidas, pero debemos ceñirnos a una.
  2. Soporte mejorado para las API de IoT . Hasta ahora, nos hemos centrado en documentar microservicios asincrónicos . Sin embargo, muchas personas utilizan la especificación para documentar sus API de IoT de MQTT y tienen diferentes necesidades, como documentar datos binarios o secuencias de bytes.
  3. API de transmisión . Agregaremos soporte para las API de transmisión a través de HTTP, ya sea utilizando codificación de transferencia fragmentada o eventos enviados por el servidor.
  4. API de eventos . Algunos de los sistemas basados ​​en mensajes que existen no tienen el concepto de "tema", sino que todos los mensajes se envían a través de un solo canal. WebSockets es un buen ejemplo. Proporcionaremos una forma de documentar eventos sin la necesidad de "temas". Una API famosa que utiliza este tipo de patrón es la API de mensajería en tiempo real de Slack .

Francisco también señala que ha habido algunos otros colaboradores que ayudaron en el proceso de modelado de la versión 2, como Bruno Pedro , Mike Ralphson , Justin Karneges , entre otros.

Conclusión

AsyncAPI es un ejemplo de algo que hace una cosa y lo hace extremadamente bien. Está claro que AsyncAPI está diseñado específicamente para la legibilidad de la máquina y funciones relacionadas.

En particular, AsyncAPI ciertamente puede otorgar grandes ganancias y beneficios a aquellos que buscan una opción que permita mayores habilidades de generación. Debido a que AsyncAPI está centrado en la máquina y permite la generación de código y documentación, funciona bien para la iteración automática, lo que resulta en un mayor potencial de crecimiento y desarrollo.

Por supuesto, AsyncAPI no es el fin de todo. Si bien el argumento podría hacerse para " cualquier función de API es esencialmente un mensaje ", ese no siempre es el caso, especialmente con las API especializadas y las API computacionales distribuidas. En tales casos, AsyncAPI puede ser bueno para la legibilidad de su máquina, pero no necesariamente apropiado para un sistema no controlado por mensajes.

Dicho esto, es una gran solución para lo que hace y debe ser evaluada por aquellos que ejecutan implementaciones y sistemas basados ​​en mensajes, especialmente si desean legibilidad por máquina. ¿Cuáles son sus opiniones sobre AsyncAPI? ¡Háganos saber en los comentarios a continuación!

Más sobre la API Async:

  • Presentamos la especificación AsyncAPI
  • Página principal

Publicar un comentario

0 Comentarios