Header Ads Widget

Ticker

6/recent/ticker-posts

AsyncAPI vs OpenAPI: ¿Cuál es la diferencia?

 


El mundo de las API es a menudo uno de estándares, intereses y soluciones en competencia. Si bien tendemos a hablar del espacio de API como una comunidad cohesionada, la realidad es que las API en Internet abarcan algo más universal.

En el espacio de documentación de API , esto finalmente se reduce a una cuestión de consumo. ¿Quién usa realmente la documentación? ¿Para qué sirve esa documentación? ¿Cómo impulsa el producto y aumenta su valor?

Hoy en día, vamos a buscar soluciones de documentación para los dos muy grandes tipos de API: API abierta y AsyncAPI . Ambas soluciones generan documentación legible por máquina, un concepto que discutiremos en breve, pero lo hacen para tipos muy diferentes de API.

¿Por qué Document?

La documentación es universal para proyectos técnicos. Tanto es así que a menudo se considera tan importante como el código en sí. La documentación de la API es esencialmente una biblia de consumo, utilización y contextualización: tiene el propósito no solo de informar al usuario final, sino de contextualizar y explicar esa información para que sea útil para alguna aplicación.

Hay dos tipos básicos de documentación. La documentación legible por humanos  informa al usuario final y explica la información en un método que puede ser fácilmente consumido por un ser humano. Esta es la forma de documentación con la que la mayoría de las personas probablemente estén familiarizadas. Dicha documentación no es únicamente técnica. A menudo vemos manuales de usuario y otra documentación de ayuda en productos minoristas comunes, descargas de software, etc.

El tipo opuesto de documentación es legible por máquina . Como su nombre indica, se ocupa únicamente de proporcionar documentación técnica que las máquinas puedan analizar, comprender y utilizar. A diferencia de la documentación legible por humanos , que se usa principalmente para la comprensión y referencia de nivel básico, la documentación legible por máquina se usa a menudo para ingerir y producir un subproducto o integración. Esta documentación se puede utilizar para desarrollar nuevas herramientas , generar nuevos datos o incluso desarrollar capas de compensación para facilitar una mejor comunicación entre API.

Como se indicó anteriormente, las dos soluciones siguientes son legibles por máquina. Sin embargo, lo que documentan específicamente es dónde vemos divergencia.

Lea también:  Guía definitiva para más de 30 soluciones de documentación de API

OpenAPI

Especificación de OpenAPI

La especificación OpenAPI se puede utilizar para asegurar y acelerar el ciclo de vida de la API.

La especificación OpenAPI , conocida anteriormente como Swagger, es una solución que produce documentación legible por máquina para las API REST. Desarrollado inicialmente en 2010, Swagger fue adquirido posteriormente en 2015 por SmartBear Software. A medida que se desarrolló y expandió Swagger, se lanzó la Open API Initiative para desarrollar y promover aún más el conjunto de herramientas Swagger en un formato abierto, respaldado por los principales actores de la industria para garantizar la estandarización y el soporte. En 2016, Swagger pasó a llamarse oficialmente Especificación OpenAPI.

OpenAPI es independiente del lenguaje y se utiliza para generar automáticamente documentación para un amplio conjunto de funciones, métodos, parámetros, modelos y más. El principal punto de venta detrás de OpenAPI es que, al unificar y estandarizar la documentación de esta manera, las bibliotecas cliente , el código fuente, los ejecutables y la documentación se sincronizan de forma nativa, ya que la documentación de la especificación en sí se utiliza para generar la mayor parte del resto.

Agregue a esto la utilización declarativa de recursos, lo que significa que el usuario final no necesita tener ningún conocimiento de la implementación del servidor, los recursos, el acceso al código del servidor, etc. para comprender y consumir los servicios, y usted tiene una muy buena solución sólida para servicios web RESTful .

Relacionado:  ¿Qué debe considerar antes de la adopción de OpenAPI?

AsyncAPI

AsyncAPI  comenzó como un proyecto paralelo en Hitch (API Changelog) y luego fue fundado por Fran Méndez. Los desarrolladores de AsyncAPI identificaron la falta de herramientas en el espacio basado en mensajes y, cuando se les presentó un conjunto abundante de herramientas para las API HTTP, decidieron que faltaba una pieza de estandarización en las especificaciones de la documentación.

A partir de esta necesidad identificada, comenzaron a buscar una solución para los sistemas de especificación estandarizados basados ​​en mensajes. Formularon una "teoría de las API" por así decirlo; básicamente, con tantos tipos de API interactivas como los servicios web RESTful , GraphQL y arquitecturas basadas en mensajes, AsyncAPI serviría como un lenguaje unificador común para los diversos formatos, protocolos y especificaciones. , lo que permite una comunicación estandarizada en el sistema basado en mensajes.

El soporte es aparentemente efectivo: según sus propios cálculos, asumiendo que crean herramientas para 6 lenguajes de programación, 4 formatos de esquema y 5 protocolos, podrían generar 120 combinaciones posibles en el espacio basado en mensajes. Esa es una cantidad significativa y que ciertamente cumple con la solución estandarizada que se diseñó originalmente.

Para obtener más información, lea:  7 protocolos buenos para documentar con AsyncAPI

Diferencias

En última instancia, las dos soluciones aquí cubren caras muy separadas de la misma moneda. Las API REST tienen una función y un propósito específicos y, como tales, requieren sus propios métodos y enfoques de documentación. Las API REST tienen, entre otras, una gran solución en forma de OpenAPI: un conjunto de métodos de documentación estandarizados para habilitar herramientas e interactividad.

Sin embargo, las API impulsadas por mensajes son muy diferentes y necesitan su propia solución que cubra las advertencias y consideraciones intrínsecas a las arquitecturas impulsadas por mensajes. Para estas API, existe AsyncAPI , que hace funcionalmente lo mismo que OpenAPI, pero con un enfoque basado en mensajes. El lema de AsyncAPI lo dice mejor: “Las API REST tienen OpenAPI. La mensajería tiene AsyncAPI. "

Es muy importante comprender que, si bien las dos soluciones tienen mucho en común, también son tremendamente divergentes. Sí, tanto OpenAPI como AsyncAPI permiten una mayor cooperación y colaboración entre diferentes API documentadas, pero OpenAPI es en gran medida una solución para REST y AsyncAPI es en gran medida una solución para arquitecturas controladas por mensajes. Son reinos completamente diferentes, a pesar de los nombres y propósitos que suenan similares.

Conclusión

En última instancia, el problema aquí es más de nomenclatura que de función. AsyncAPI y OpenAPI suenan muy similares al oído, y debido a esto, tienden a colocarse en el mismo "cubo" intelectual. Sin embargo, esta es una mala manera de ver las soluciones, ya que los propósitos divergentes pintan una imagen muy sorprendente de formas y funciones diferentes entre los dos.

En pocas palabras, adoptar AsyncAPI es una obviedad para las API basadas en mensajes, pero se puede decir lo mismo de OpenAPI para las API RESTful y, a la inversa, no hay razón para que AsyncAPI realmente surja en una conversación sobre las API RESTful o OpenAPI. para ser discutido en el contexto de arquitecturas impulsadas por mensajes.

Esperamos que esto haya aclarado algunos conceptos erróneos sobre estas dos soluciones. Háganos saber en los comentarios lo que piensa y si esto fue útil o no.


Publicar un comentario

0 Comentarios